Si2oaD/Options

From oacwiki

Jump to: navigation, search

Option settings can control

  • locations for components used by the tool both for initial setup and while it is running
  • various aspects of the display, including
    • the output target (console or browser)
    • communications options
    • output filters to attenuate the output generated (which can get voluminous on large designs, causing large XML or HTML files that take a browser some minutes to load and process)

The Options Summary section lists the various options available. The Options Details section explain additional semantics and dependencies, as well as different ways to set options during the course of program execution.

Contents

1 Defaults

All options are set to the default values (Options Summary) defined in the implementation code (si2oadglob.cpp) when the Si2oaD library is loaded into the process and the linker performs static initialization, whether

  • implicitly, because the library was linked to the application
  • implicitly, because the LD_PRELOAD technique is used (e.g., via the run or oad targets in makefile.defs)
  • explicitly, because the library is dynamically inserted into the running process (e.g., via Tcl load command)

As the final part of static initialization, one attempt is made to read a user-created .si2oadoptions file (with that predefined name), which contains any number of options settings. The search order starts with the

  • current working directory of the Si2oaD process
  • process user's $HOME/ – if no .si2oadoptions file was found in ./

2 Changing Options

At any time during execution of the application, option settings can be changed.

2.1 Setting Individual Options

Individual options may be changed interactively using, oad("o","optionname=value"). If the second argument is the empty string (or NULL, for debuggers that can use the overloaded interface) then the user will be prompted interactively for the name and value. The following fragment from a debugger session illustrates changing individual option settings from the console. 

(gdb) b 124
Breakpoint 2 at 0x8063b8d: file testcase.cpp, line 124.
(gdb) c
Continuing.
Breakpoint 2, main (argc=4, argv=0xbfffd184) at testcase.cpp:124
124 cout << "got ModNet" << modNet << endl;
(gdb) call oad(modNet)
<oaModScalarNet isPreferredEquivalent='t' id='b75d0612' name='N1' numBits='1'  sigType='signal'> <ref>sigType included even though the default value</ref>
<instTerms>
<oaModInstTerm ref='#b75d0692' termName='a'/>
</instTerms>
<occNets>
<oaOccScalarNet ref='#b75d0712' name='N1'/>
</occNets>
<oaModScalarTerm id='b75d0792' name='T1' isInterface='t' position='UINT_MAX' numBits='1' termType='input'>
<net ref='#b75d0612' name='N1'/> <ref>termType included even though the default value</ref>
<occTerms>
<oaOccScalarTerm ref='#b75d0812' name='T1'/>
</occTerms>
</oaModScalarTerm>
</oaModScalarNet>

(gdb) call oado( "o", "" )
OptionName CurrentValue Description
# Si2oadD version = 1.3.10 2007jun14
output gui                      # Output sent to [gui|console].
indent 1                        # Indent increment representing ownership
url http://localhost          # URL of the nanowww domain
port 0                          # Port for nanowww on localhost [0 = OS choice]
docroot ../si2dis               # wwwserver root location
browser firefox                 # Browser (path if not in your $PATH)
browseropts -new-window         # Override of default options for browser set above
outputpath ~/si2oad.7425        # Path location for generated output .xml & .html
deleteoutputpath t              # Delete outputpath when GUI returns to console
.xml si2oad.xml                 # XML output filename
xsltype processor               # XSLT transformation type? [none|browser|processor]
.xsl si2oad.xsl                 # Path to the .XSL source to transform raw XML into HTML
.js si2oadheader.js             # Path to the Javascript header file (si2oadheader.js)
apilink apiLinkTable.js         # Path to the apilinktable file (apilinktable.js)
.css si2oad.css                 # Path to the CSS stylesheet for the HTML
oadoc /home/226p052/doc/oa/html # Path or URL to OA doc/oa/html root
xslexe $HOME/../XML/bin/Xalan   # Path to the XSLT processor executable
xsllib $HOME/../XML/lib         # Colon-separated paths to libs needed by XSLT
.html si2oad.html               # Filename of HTML transform of XML dump
namespace Native                # oaNamespace to use for rendering all mapped names
verbose 2                       # Verbose printing of oaD progress/status messages
dllobserver 0                   # Path to dll with Observers implementation (0 if none)
maxextdata 16                   # Max bytes of Prop/AppDef to display in window (0 if no limit)
sysdatadisp 0                   # Path to exe to display Prop/AppDef data (0 if none)
dlldatadisp 0                   # Path to dll to display Prop/AppDef data (0 if none)
syscmapdisp 0                   # Path to exe to display CMap data (0 if none)
dllcmapdisp 0                   # Path to dll to display CMap data (0 if none)
dofalsebools t                  # Do Boolean attributes if false
dodefaults f                    # Do attributes with default values
dosinglebits t                  # Do SingleBitMembers for BitNets
doredundants t                  # Do 'redundant' attributes that can be inferred
doblock t                       # Do the Block Domain when dumping a Design
domod t                         # Do the Module Domain when dumping a Design
doocc t                         # Do the Occurrence Domain when dumping a Design
expandocc f                     # Expand the Occurrence tree for each OccInst
doparasitics t                  # Do parasitics
loadnetworks f                  # Load all ParasiticNetworks
donullobjs t                    # Do NULL Object references
dobbox t                        # Do BBox report (and calculation side-effects)
casesensitive t                 # Default case-sensitivite setting for regex
regexsticky t                   # If t && regex set, it applies to all subsequent oad()
xdelimescape \                  # Regex escape char used with itself and type, name delims
xdelimtype b                    # Regex delimiter char between Objects [b means blank]
xdelimname =                    # Regex delimiter char between name components
delimLCV =                      # Delimiter char between L/C/V name components
maxownerlevels 0                # Max owner chain depth to display (0 shows all data)
maxcollentries 0                # Max # of Collection entries to display at a time
dllsorters ../si2dis/si2oadSortName,../si2dis/si2oadSortOaTypeName,../si2dis/si2oadSortInfoType  

Use t or f for Booleans. Use first 3 letters for namespace:
Native Cdba Verilog Vhdl Spice Spf Spef Lef DefUnix Windoze

TYPE optionName newValue<ENTER> [/ to CANCEL] dodefaults f
[si2oad] Setting options:
[si2oad] ...WWW server docroot = /home/d/docroot
[si2oad] ...No Observers DLL specified for load.
[si2oad] ...Sticky regex now OFF:
[si2oad] call oad("[rege]x","...") before every oad call to activate regex.
(gdb) call oad(modNet)
<oaModScalarNet isPreferredEquivalent='t' <ref>sigType omitted with dodefaults=f>/ref>
  id='b75d0612' name='N1' numBits='1'>
  <instTerms>
<oaModInstTerm ref='#b75d0692' termName='a'/>
</instTerms>
<occNets>
<oaOccScalarNet ref='#b75d0712' name='N1'/>
</occNets> <ref>termType omitted with dodefaults=f>/ref>
  <oaModScalarTerm id='b75d0792' name='T1'
isInterface='t' position='UINT_MAX' numBits='1'>
<net ref='#b75d0612' name='N1'/>
<occTerms>
<oaOccScalarTerm ref='#b75d0812' name='T1'/>
</occTerms>
</oaModScalarTerm>
</oaModScalarNet>

2.2 Options File

Multiple options may be changed interactively by calling, 

oad("r","filename")

The file name specified must contain option settings in the same format as that created by, 

oad("w","filename")

Any number of option settings may be included in the file. These overwrite existing option settings so it is not necessary to have the complete set of values in the file. Option assignments in a file are read and set sequentially; so if the same option value is set more than once in a file, the option will end up with the last value set. The following gdb session fragment first writes all option settings to a file, then uses sed to change one option, then reads that file to effect the option change.

Save current option settings: 

(gdb) call oado( "w", "save.opts" )

Edit one of the options in that file: 

(gdb) shell sed ' s/^output *.*/output gui/' save.opts >gui.opts

Read file to reset options 

(gdb) call oado( "r", "gui.opts" )

3 Si2oaD Options Summary

Option ID Value CHOICE types may be abbreviated to the first unique letter(s) Description

3.1 Output Settings

verbose
UINT DEFAULT = 0
Verbose threshold
output
STRING: console | gui DEFAULT = console
Display target

3.2 Output Rendition Controls

namespace
Native | Verilog | Lef | Def | Unix | Windows | Spice | Cdba | Vhdl | Spf | Spef
DEFAULT = Native
oaNamespace (string name) to use for rendering all mapped names
indent
UINT DEFAULT = 1
Indent increment
alwayssort
BOOL: t | f DEFAULT = f
Always sort Collections
delimLCV
CHAR DEFAULT = /
Delimiter between L/C/V name components

3.3 GUI Settings

These options apply only when the option output=gui:

url
URL DEFAULT = http://localhost
URL for nano-www communications
port
INT DEFAULT = 0
Port number for the nanowww server host
docroot
PATH DEFAULT = $Origin/../../../data/si2dis
Document root for the nanoserver
outputpath
PATH DEFAULT = ../si2dis
Directory for XML & HTML outputs
.xml
FILENAME DEFAULT = si2oad.xml
Output XML filename
browser
PATH DEFAULT = firefox
Browser executable (for GUI output).
browseropts
STRING DEFAULT = -new-window (if browser==firefox; else empty)
Browser command line run options.
xsltype
browser | processor | none DEFAULT = browser
XSL transformation of XML to HTML

3.3.1 XSL Settings

These options apply only when XSL is to be used to transform the XML output into (active) HTML; i.e., when xsltype=browser|processor.

.xsl
PATH DEFAULT = si2oad.xsl
Path to .XSLT source to transform raw XML into HTML (ignored if the processor option is set to "none")
.js
PATH DEFAULT = si2oadheader.js
Path to Javascript header (normally, do not change)
apilink
PATH DEFAULT = apiLinkTable.js
Path to Javascript apilinktable (normally, do not change)
.css
PATH DEFAULT = si2oad.css
Path to the CSS stylesheet for HTML
oadoc
PATH DEFAULT = [Si2_ROOT_OA"/doc/oa/html"]
URL to OA API doc tree html/ root
abortsignal
PATH DEFAULT = 0
SIG to use for command-line kill of Sorter DLL activity (0 disables). On SuSE Linux list of available signals from /usr/include/bits/signum.h or `man -S7 signal`

3.3.1.1 XSL Processor Settings

The following options apply only when output==gui && xsltype==processor:

xslexe
PATH DEFAULT = ../../XML/bin/Xalan
Path to the XSLT processor executable
xsllib
PATHLIST DEFAULT = ../../XML/lib
Colon-separated list of paths to libs needed by the XSLT processor
.html
PATH DEFAULT = si2oad.html
Filename (no path) of HTML transform of XML (normally, do not change this)

3.4 Output Data Filters

dofalsebools
BOOL: t | f DEFAULT = f
Display (true) or omit (false) boolean attributes with false values
dodefaults
BOOL: t | f DEFAULT = t
Display (true) or omit (false) attributes with default values.
dosinglebits
BOOL: t | f DEFAULT = t
Display (true) or omit (false) single-bit members of BitNets
doredundants
BOOL: t | f DEFAULT = t
Display (true) or omit (false) 'redundant' attributes that can be inferred from their context in the output.
donullobjs
BOOL: t | f DEFAULT = t
Display (true) or omit (false) NULL object references.
dobbox
BOOL: t | f DEFAULT = t
Display (true) or omit (false) all bounding Boxes.
maxownerlevels
INT DEFAULT = 1
Traverse and display only the specified number of nested levels of the Object ownership hierarchy,
maxcollentries
INT DEFAULT = 1
The maximum number of members of a Collection to display at a time (especially useful with large Collections of Objects)

3.4.1 Domains

doblock
BOOL: t | f DEFAULT = t
Display (true) or omit (false) the Block Domain when displaying a Design. References to Block Objects from other Domains will will be displayed in either case.
domod
BOOL: t | f DEFAULT = t
Display (true) or omit (false) the Module Domain when displaying a Design. References to Module Objects from other Domains will will be displayed in either case.
doocc
BOOL: t | f DEFAULT = t
Display (true) or omit (false) the Occurrence Domain when displaying a Design. References to Occurrence Objects from other Domains will will be displayed in either case.
expandocc
BOOL: t | f DEFAULT = t
Expand the entire Occurrence tree automatically.

3.4.2 Other Containers

doparasitics
BOOL: t | f DEFAULT = t
Display (true) or omit (false) all parasitics
loadnetworks
BOOL: t | f DEFAULT = t
Load all ParasiticNetworks automatically
autoopentech
BOOL: t | f DEFAULT = t
Automatically open the Tech for the Lib [if exists()].
autoopendmd
BOOL: t | f DEFAULT = f
Automatically open the DMData for a DMContainer [if exists()].
autoskipdmd
BOOL: t | f DEFAULT = f
Do not traverse into the DMData for a DMContainer [even if open in RTM].

3.4.3 Iters

iterinsts
OR of BITS DEFAULT = oacInstIterAll

0x0000 oacInstIterAll
0x0001 oacInstIterSingleBit
0x0002 oacInstIterNotImplicit

iterinstterms
OR of BITS DEFAULT = oacInstTermIterAll

0x0000 oacInstTermIterAllNotHidden
0x0001 oacInstTermIterSingleBit
0x0002 oacInstTermIterNotImplicit
0x0004 oacInstTermIterEquivNets
0x0010 oacInstTermIterAll

iternets
OR of BITS DEFAULT = oacNetIterAll

0x0001 oacNetIterAll
0x0002 oacNetIterSingleBit
0x0004 oacNetIterBundle
0x0010 oacNetIterPreferred
0x0020 oacNetIterNotImplicit
0x0040 oacNetIterGlobal

iterterms
OR of BITS DEFAULT = oacTermIterAll

0x0001 oacTermIterAll
0x0002 oacTermIterSingleBit
0x0004 oacTermIterBundle
0x0010 oacTermIterNotImplicit

3.4.4 Regex Controls

casesensitive
BOOL: t | f DEFAULT = t
Use case-sensitive (true) or case-insensitive (false) matching of each Object name
regexsticky
BOOL: t | f DEFAULT = t
If a regex pathExpression has been set via call to oad("x","..."), then use regex matching:
  • (if f) Once only, on the very next OAD call to display data
  • (if t) For all OAD calls (until regexsticky is set to f)
xdelimescape
CHAR DEFAULT = 0
Escape character to enable xdelimtype and xdelimname characters to be used as literal characters. 0 means none.
xdelimtype
CHAR DEFAULT = b
Delimiter, at least one of which, that must precede each (except the first) typeRegex in a regex pathExpression. The letter b indicates a blank.
xdelimname
CHAR DEFAULT = =
Delimiter, exactly one of which, that must precede each nameRegex in a regex pathExpression.

3.5 User Code Extensions

maxextdata
UINT DEFAULT = 8
The maximum number of bytes of Prop or AppDef data to display embedded in the XML or HTML output.
sysdatadisp
PATH | 0 DEFAULT = $EDITOR
System executable for display of Prop or AppDef data in case that the amount of data exceeds maxextdata.
dlldatadisp
PATH | 0 DEFAULT = 0
DLL to use for display of Prop or AppDef data in case that the amount of data exceeds extdatamax. If not = 0, the specified DLL will be used regardless of any sysdatadisp setting.
syscmapdisp
PATH | 0 DEFAULT = $EDITOR
System executable to use to display Prop or AppDef data in the case that the amount of data exceeds maxextdata (or 0 if none).
dllcmapdisp
PATH | 0 DEFAULT = 0
DLL to use to display CMap GCell data larger than maxextdata. If not = 0, the specified DLL will be used regardless of any syscmapdisp setting.
dllobserver
PATH | 0 DEFAULT = si2oadObserve
List of DLL paths(comma-separated) implementing any number of oaObservers (or 0 if none).
dllsorters
PATHLIST | 0 DEFAULT =

  si2oadSortName,   si2oadSortInfoType,   si2oadSortOaTypeName

List of DLL paths (comma-separated) implementing any number of sort routines for arrays of oaObjects (or 0 if none). The .so suffix is optional. If libsi2oad.so is linked with $ORIGIN (the default), a DLL located in the same directory as oad will not need a path prefix.
dlldir
PATH | 0 DEFAULT = $Origin
Directory containing plugin DLLs (so each plugin DLL does not need a path).

4 Option Details

Shell Meta-Character Expansion

Options that represent path names in the file system all can use Bourne shell meta-characters, which will automatically get expanded to an actual path name by the POSIX wordexp() function. Useful metas include those in the table below:

Common Path Meta-Characters
Character Expanded to
. The current directory
.. The current parent directory
$VARIABLE The current value for an envrionment variable
~ Users $HOME director

The following table illustrates how to set options from the command line.


Example Calls to Set Options
Task Input to gdb
Send data display output to console call oad("o","output=console")
Send data display output to browser call oad("o","output=gui")
Omit any false bool attributes from the display call oad("o","dofalsebools=f")
Limit console messages to critical information only call oad("o","verbose=0")
Print as much status/state information as possible call oad("o","verbose=9999")
Set the default for regex-name matching to case-insensitive call oad("o","casesensitive=f")
Omit the Module Domain from the display call oad("o","domod=f")

4.1 verbose

The verbose option may be set to any integer ≥ 0 to control how much diagnostic output is generated. As the value increases, more messages are printed to the console (regardless of the setting of the output option). A setting of 0 prints only important errors to that must be seen.

4.2 output

This option determines the target of the output generated by calls to oad(). If the value is,

  • console, the XML output will be sent to stdout.
  • gui, the output will be sent to a browser for display as either XML or HTML, depending on the setting of the xsltype option. Once the browser has been launced and data is being displayed in GUI mode, many additional requests for additional RTM data can be made of the nanoserver driving the display. At some point, however, the user will want to return control to the console (i.e., stdin) in order to communicate with the debugger again.To switch back to the console from the GUI,
  • Press the button a[[Image:]]t the top
  • If all browser instances were deleted before this button could be pushed, simple open a new browser to URL: http://localhost:PPPPP/quit (that is, with same URL and Port options that are listed in the console output just prior to opening of the original browser instance).

Switching back with the button or a “quit” URL request to the nanoserver will gracefully return control to the debugger at the exact point where the oad() call was executed without the need to send an interrupt signal.

4.3 indent

If the option output=console, the indent option sets the number of spaces to indent each successive level of nested containment or ownership.

In the case output=gui, the file named in the .css option controls the size of indents in the HTML displayed by the browser.

4.4 alwayssort

If the value of this alwayssort=t then Collection entries will be sorted by default using the first sorter DLL in the list. If no sorterDLLs have been loaded successfully, this option is set to f automaticallly. Using this option is the only way to coerce the stand-alone si2dis program to sort Collections.

4.5 url

When GUI is selected for the display output, a skeletal HTTP server (nanoserver) is started and becomes the source of data for the interaction with the browser . All data is communicated to the browser from this nanoserver on the port specified by the port option.

During the life of a display, the user may make requests for additional Objects that were not included in the original set of data being displayed. For example, if oad(someNet) invokes the browser to display that Net, and the user clicks on the block=0xbc7784 association reference to that Net's Block, Javascript on the page will cause a request to be sent to Si2OAD for the data using the same URL used to open the browser.

Prior to v2.7: By default, url is set to http://localhost

As of v2.7: By default, url is set to the empty string. If:

  • url is set in the .si2oadoptions file, its value will be used as-is. This value must have the http:// prefix included with the hostname or IP.
  • url is not set in the .si2oadoptions file,
    • First, the nanoserver (si2oadwww.cpp) will try to detect the IP of the machine on which the Si2oaD process was started. A call to ioctl(SIOCGIFCONF) is used to get the list of AF_INET interfaces.
      • The first one that is not a 127.0.0 IP will be used as the URL in the browser system() call (prefixed by http://). This may be the wrong value in cases where the nanoserver machine has more than one external internet interface (e.g., a machine that is a firewall for an internal LAN).
      • If only 127.0.0 IP addresses are found, then localhost is used, which means that if the browser is not running on the same machine, this will resolve to the wrong IP.
    • If the call to ioctl fails, then localhost is used

In all cases where the URL gets set to localhost, whether explicitly in the .si2oadoptions file or implicitly by the nanoserver "detection" code, the url option must be used to force the right name or IP to the nanoserver that is running on a different machine from that of the browser.

These scenarios have been successfully tested:

  • ssh -X to a different machine on the same LAN
      • login to machine 1 on a LAN
      • ssh -X to machine2 on the LAN
      • run Si2oaD
      • The browser displays on machine 1.
  • DHCP assignment
    • connect to cable modem and get assigned an IP
    • run OAD, which finds the assigned IP and uses it to spawn the browser (both on the same machine, but using the DHCP-assigned IP instead of localhost). Note: this will fail if the cable provider switched IPs in the middle of the OAD session, which a service provider is allowed to do if the customer does not have a static (assigned) IP.

4.6 port

The port used by the nanowebserver can be explicitly assigned using this option. Typically, however, a 0 is used to let the operating system pick an unused socket to avoid interfering with other socket traffic.

4.7 docroot

If GUI mode is selected (output=g), and XSL processing will be used to convert the XML output to HTML, then several files are required for the browser to display that HTML properly. The code will check a manifest of the files needed each time the docroot is set – including the first time on start-up, the default “../si2dis” default location in case the .si2oadoptions file does not change that.

The current manifest is defined by the docrootFiles array in the code; for example, for 1.3.2 it was: 

 const char *docrootFiles[] = { 
   "si2oadUserGuide.pdf",
   "si2logotrim.gif",
   "si2oad.xsl",
   "si2oad.css",
   "apiLinkTable.js",
   "si2oadheader.js",
   "favicon.ico",
   "regexChoices.html",
   "regexError.html",
   "quit.html"
 }

These files can be located in any directory in which the owner of the process executing Si2OAD has read/execute permission (since the browser must be able to change to that directory and read the files). The code will not copy the files there automatically, but it will note each file that is missing from the manifest in a console error message.

Typically, the same docroot will be defined for any number of users simultaneously running OAD since the manifest files do not change for a given version of the code. The outputpath, on the other hand, almost always needs to be a different directory, unless only one user at a time will be running the tool.

4.8 outputpath

When output=g, this directory specifies the location of the output data (including error messages that display in pop-up windows) generated by each oad() call, as well as calls within the GUI environment that cause incremental data to be sent by the nanoserver to the browser. If more than one user could be running OAD at the same time, a unique outputpath must be created for each user, since the same output file names are used. Even if each user promises to use a different .xml and .html names, extension and Cmap data, as well as error message content, all use default, currently changeable names. Since multiple users might well be using a common docroot, the outputpath should be different from that directory. A popular way to uniquify this directory name is to attach the special token, $PID, to the name. For this option only, the code will replace this special text token with the current process ID. This replacement happens before the string is then expanded for shell meta characters.

4.9 browser

The value of this option sets the executable to be used in a system() call to present the OAD output in a GUI. If that executable is not in $PATH then a path must be specified that is either absolute or relative to the location of Si2oaD's library. Raw XML display and (browser client-side) XLST processing has been successfully tested with:

  • Linux:
    • Firefox 1.0.7, 1.5.0.1, 2.0
    • Mozilla 1.4
    • Chrome
  • WIN:
    • Netscape 7.2
    • IE 6.0
    • Firefox 2.0
    • Mozilla 1.7.13

For the latest list of platform/compiler/browser combinations tested, see the “Readme Notes” on the download page for a given release.

4.10 browseropts

With no browseropts option setting, the OAD code uses the value of the browser option setting as a key into an internal map of browser/command-arg settings that have been experimentally determined to be optimal. Those command-line args (if any) are used in the system() call that spawns the browser. However, any value set for the browseropts in the .si2oadoptions will be used instead. All characters of this value, up to a # or NEWLINE, will be included on the command line.

4.11 xsltype

Meaningful only if output=gui, the following xsltype settings are recognized:

  • none:The output will be raw XML.
  • browser:The native XSLT engine of the browserwill be used.
  • processor:An external XSLT processor (the path set in the xslexe option) will be used.

4.12 .css

The path to the CSS style file that governs the rendition of the HTML in the browser in the case that option output=gui.

4.13 xslexe

If xsltype=processor, the value of this option is the name of the executable that will be used to transform the output XML into HTML for use by the tool named in the browser option. If this XSLT processor is not in the PATH, then a path name must be specified that is either absolute or relative to the location from which the Si2OAD library was loaded.

4.14 xsllib

If xsltype=processor, the value of this option is the colon-separated path list to be appended to the LD_LIBRARY_PATH to resolve shared libraries requirements (if any) of the xslexe executable. Each path in the list must be either absolute or relative to the location from which the Si2OAD library was loaded.

4.15 loadnetworks

Setting loadnetworks=t wil force all ParasiitcNetworks (and their partitions, if any) to be loaded by OAD automatically.

Even if this option is f, individual Networks can be loaded interactively from the GUI by clicking on the LOAD hot link. Such Networks are automatically unloaded immediately after the display so the run-time state remains as it was prior to the oad() call.

4.16 dobbox

Displaying a bbox causes a recalculation, which can change the RTM state. This violates the “do no harm” precept that is a core of OAD. However, if the user needs to see this data updated dynamically in the output, setting dobbox=t will cause all bbox data to be calculated. Even in this case, however, bboxes will be updated only to the extent that the OA API can manage. For example, requesting the bbox of a Block will not cause binding of all its Inst to unbound masters; hence, even a recalculated bbox might not be accurate if changes were made to an unbound Inst's master since the data was last stored on the Inst.

4.17 maxownerlevels

This option is perhaps the most valuable to maintain fast response using a GUI to traverse large Designs. If maxownerlevels=0, the Object ownership hierarchy will be traversed completely, sending all data to the output stream. For large Designs, this can be a huge amount of XML.

If the output target is a browser, the XSLT process produces an even larger amount of HTML, which will result in very sluggish browser response to the point of crashing some browsers with hundreds of megabytes of HTML. This problem can be controlled by setting maxownerlevels to some low number, like 1. This results in very fast loading for even the largest Designs

Limiting the depth of traversal when the output is being sent to the console can also be valuable, enabling incremental selection of a more limited set of interesting Objects for extended traversal. Otherwise, the display terminal can become quickly overwhelmed with data, leaving only the last few bits of data. The complete output can be captured even on the console if

  • the console tool's history buffer has been set to “infinite”.
  • an emacs shell buffer is used.

On the other hand, if the goal is to capture or archive a complete design in XML, sendig the output to a file, then it may be necessary to set maxownerlevels=0, or to a number. larger than 1. Fortunately, capturing just the XML takes only a fraction of the time it takes to transform it to HTML and load that nto a browser.

When this option is set to limit depth of traversal, when that limit is reached, instead of data as the indented contents of a parent Object, a special sentinel tag is planted to indicate the model extends deeper at that point. When output=gui, the sentinel itself will not display; however, clicking on the leading + for the Object entry that contains such a sentinel will cause a real-time callback to the nanoserver for automatic traversal and display of an additional maxownerlevels number of container levels. This enables incremental display of only the parts of the RTM of interest to the developer, thereby reducing the time it takes for any given XSL transformation and browser load of HTML data.

4.18 maxcollentries

Another option to improve GUI response with large Designs, if maxcollentries=0, every member (each with its attribututes and owned Objects, recursed to the level specified by maxownerlevels) of each Collection will be sent to the GUI as it opens. For a Design with a 100,000 Insts and a half million Nets, this can be a huge amount of XML.

By specifying a small, non-zero maxcollentries value, only that many Objects in each Collection will be displayed at a time, with a ... at the end of the Collection, which indicates there are more members to be seen. Clicking on that ... will cause the nanoserver to send the next maxcollentries batch of members to the browser. After a few batches are displayed, CTL-clicking the leading – will invoke the regex/sort pop-up, enabling successive filtering passes to winnow down the Collection into something manageable.

4.19 expandocc

To avoid altering the RTM, OAD will normally not call getMasterOccurrence() for any Insts or OccModuleInstHeaders. If expandocc=t, then for each oaOccInst, an Occurrence hierarchy will automatically be bound into the RTM with the owner OccInst or OccModuleInstheader as the container for the resulting Occurrence. Any OccInsts and OccModuleInstHeaders within that Occurrence will also be expanded, recursively to the frontier.

Even if this option is f, individual OccInst master Occurrences can be expanded interactively by clicking on the EXPAND hot links. Occurrence trees expanded in this fashion will be destroyed automatically when the current GUI session ends, thereby leaving the RTM in its original, unexpanded state.

If the RTM already had an Occurrence master expanded (by the application's activities) at the time OAD is invoked, that Occurrence tree will be displayed regardless of the expandocc setting, since it already existed in the data.

4.20 dodefaults

The default values of many attributes can be inferred or looked up easily. Setting the dodefaults=f can further reduce the volume of output. Attributes and their default values that will be skipped (if dodefaults==f) include the following:

  • isPreferredEquivalent == t (unlike most oaBooleans, this default value is t)
  • double == 0.0
  • float == 0.0
  • int == 0
  • TimeStamp == 0
  • String if isEmpty()
  • refCount == 1
  • Most enums == 0 (i.e., the first enum in the list, except when that is not a reasonable default value for the particular enum)
  • OccNet/OccInst pathName if the same as the name
  • Arrays if both:
    • size == 0
    • numElements == 0

4.21 doredundants

The values of severay attributes (typically those common to a main category of Objects, such as DesignObjects or DMObjects) can be inferred from their context in the display. Setting the doredundants option to f suppresses these from the display. This can appreciably reduce the volume of output providing for faster output generation as well as making it easier to pick out the more important attributes from a sea of data. Eamples of such attributes include,

  • References to the owner/container object if it is displayed above
  • The domain of an Object
  • isContainer for DM Container Objects
  • isPreferredEquivalent if no equivalent nets
  • The count/numObjects/numBits in a Collection since the list itself appears in the display
  • "has*" Booleans, since the Object itself will appear in the display
  • OccNet "span" of only the OccNet itself

4.22 Extension Data

Setting the option, maxextdata, to a reasonably small number of bytes can prevent cluttering the output with potentially voluminous extension data values of AppProp, DataAppDef, and VarDataAppDef extension Objects. If that value for such an extension exceeds the set limit, a ... will be included after the bytes displayed to indicate there is more data in the value. Clicking on this ... will invoke a confirmation dialog. The complete data value will be displayed in a separate window if the value for option

  • sysdatadisp is set to the name of an executable to be invoked (in the background with &) via system() call in a separate process. The data is saved to a temporary file, which is passed to the executable as its first argument.
  • dlldatadisp is set to the name of a shared object (DLL) to be loaded into the current process space. The DLL must use C linkage to declare the entry point, ""

In either case, an absolute path to the data display tool must be used if that tool is not in, respectively, the PATH or shared object load path for the process.

4.23 CMap Data

Setting the option, maxextdata, to a reasonably small number of bytes can prevent cluttering the output with potentially voluminous CMap data. If that data exceeds the set limit, a Qaz will be displayed.

Edit the .si2oadoptions file. Set the sysdatacmap option to emacs (or your favorite text editor) using an absolute location if not in the PATH of the current process.

Run the testcase, test1.cpp, setting a breakpoint just before the deleteSupplyDemand() is executed for the CMap. 

 make oad TEST=test1
 b 710
 c
 call oad()

In the GUI open the first design junk/schematic

  • open the Block
  • open the CMAP
  • slide to right of display line and click on ...
  • ask for layer 201

This should open the data in emacs as a separate system() call.

Alternatively, you can edit .si2oadoptions file and set dllcmapdisp to the dll for it that I included (which is just a system call to emacs anyway): si2oadCMapViewer.so

Retrieved from "http://www.si2.org/openeda.si2.org/oacwiki/index.php/Si2oaD/Options"
Personal tools