Si2oaD/si2dis
From oacwiki
The si2dis tool enables use of Si2oaD from the command line to display persistent data – without needing an application and gdb. In other words, si2dis is a stand-alone, command-line front-end for the Si2oaD libraries that
- reads some command line options,
- maybe makes use of a library definition file,
- calls oad() to export some subset of disk data in the Si2oaD XML format
(or as active HTML in a browser, depending on the .si2oadoptions settings).
The source files, si2dis.* (in the si2dis/ directory) comprise this command-line front-end for the Si2oaD shared objects (DLLs). This front-end can be invoked from either
- The executable itself
- A script wrapper for the executable
- The makefile targets provided with the Si2oaD download package
Contents |
1 Invoking si2dis
The command line is set up slightly differently, depending on how si2dis is being invoked
- The compiled executable (linked object file)
$PREFIX/bin/$PLATFORM_$BITS/$MODE/si2dis
- The OA translator wrapper (a shell script) in $PREFIX/bin, which is set up the same way the OA translator wrappers (lef2oa is used as a model) are in $Si2_ROOT_OA/bin
$PREFIX/bin/si2dis
- One of the simple shell script wrappers
$PREFIX/bin/si2dis.sh $PREFIX/bin/si2dis.csh
2 Running the Executable
The make link step uses $ORIGIN to enable si2dis to find the Si2oadD libraries, which are all in the same directory. To this end, si2dis itself is copied into the lib/ directory during install, so that its libraries will be in the same location. Consequently, only the path to the OA libraries needs to be passed to si2dis if it is run out of that lib/ directory; for example,
LD_LIBRARY_PATH=$Si2_ROOT_OA $OAD_BIN/si2dis LD_LIBRARY_PATH=$Si2_ROOT_OA $OAD_BIN/si2dis -d -lcv Lib/Sample/schematic
Running gdb on si2dis would look something like the following:
LD_LIBRARY_PATH=$Si2_ROOT_OA gdb $OAD_BIN/si2dis run -d -lcv Lib/Sample/schematic
3 Using an si2dis Script Wrapper
The si2dis fron-end can be run directly from the command line without the Si2 makefile harness. Two different kinds of script wrappers are built automatically for si2dis
- An OA-translator-style script wrapper:
OA_BIT=64 OA_MODE=dbg $PREFIX/bin/si2dis OA_BIT=64 OA_MODE=dbg $PREFIX/bin/si2dis
- Simple BSH and CSH wrappers created automatically by the make, install, run, and gdb targets (with the various paths and settings baked in):
$PREFIX/bin/si2dis.sh -lcv Lib/Sample/schematic $PREFIX/bin/si2dis.csh -lib Lib1a -tech
4 Using make
The make system included as part of the download package includes several targets of use in running and debugging. The tool can be invoked as follows to run the default input arguments that are set in the Makefile:
make run Si2_ROOT_OA=/home/oa/p004
The Makefile automatically sets various environment values needed, as well as default arguments for a test design. Default arguments supplied by the Makefile can be changed by overriding the value of the INPUT make variable. For example, the following INPUT setting will cause si2dis to print its help information:
make run Si2_ROOT_OA=/home/oa/p004 INPUT="-help"
The debugger can be invoked via the gdb: target as follows:
make gdb Si2_ROOT_OA=/home/oa/p004 INPUT="-lcv Lib/Sample/schematic"
The make target automatically creates a .gdbinit file with settings for the
- PATH and LD_LIBRARY_PATH environment variables
- directory list (for OA and Si2oaD source files)
- an initial breakpoint at the start of main()
- a run statement with the INPUT options
For example:
set env PATH :::/home/d/bin:/usr/local/bin:/usr/bin:/bin:/usr/bin/X11:/usr/X11R6/bin:/usr/games:/opt/kde3/bin:/usr/lib/mit/bin:/usr/lib/mit/sbin:/usr/NX/bin:/usr/lib/qt3/bin:/cad/bin:/home/oa/p004/bin/linux_rhel40_gcc44x_64/dbg set env LD_LIBRARY_PATH /home/labs/si2dis/../lib/linux_rhel40_gcc44x_64/dbg:/home/oa/p004/lib/linux_rhel40_gcc44x_64/dbg directory /home/oa/p004/oa/src/base: /home/oa/p004/oa/src/tech: /home/oa/p004/oa/src/design: /home/oa/p004/oa/src/dm: /home/oa/p004/oa/src/cm: /home/oa/p004/oa/src/plugIn: /home/oa/p004/oa/src/wafer: /home/oa/p004/oa/src/common: /home/oa/p004/oa/src/util: /home/oa/p004/oaLang/src/base: /home/oa/p004/oaLang/src/help: /home/oa/p004/oaLang/src/info: /home/oa/p004/oaLang/src/plugIn: /home/oa/p004/oaLang/src/tcl: /home/oa/p004/oaLang/src/tclBase: /home/oa/p004/oaLang/src/tclCommon: /home/oa/p004/oaLang/src/tclEngine: /home/oa/p004/oa/plugIns/CMExportSample: /home/oa/p004/oa/plugIns/DMFileSys/src/fileSys: /home/oa/p004/oa/plugIns/DMFileSys/src/base: /home/oa/p004/oa/plugIns/NativeText: /home/oa/p004/oa/plugIns/PcellCPP: /home/oa/p004/oa/plugIns/RQXYTree: /home/oa/p004/oa/plugIns/CMTrackingSample: /home/oa/p004/oa/plugIns/DMTurbo/src/base: /home/oa/p004/oa/plugIns/DMTurbo/src/client: /home/oa/p004/oa/plugIns/PcellScript: /home/oa/p004/oa/plugIns/VCSample: ../si2dis b main run -lcv Lib/Sample/schematic
This .gdbinit file can be copied after a single pass using make, then edited and reused with one of the direct or script executable techniques.
In the si2distest/ directory, where testcase programs reside, the oad target should be used:
make oad Si2_ROOT_OA=/home/oa/p004 TEST=test1
The gdb target still works but the oad library will not be injected. The result would be an ordinary debug session on the testcase. (Note that the oad target is inappropriate when running against si2dis itself, since no LD_PRELOAD injection of oad is necessary because it is already linked into si2dis.)
5 Command-Line Arguments
Command line arguments specify the Lib, Cell, or CellView primary Object to be displayed.
- If a LIBPATH is specified (which could be a lib.defs file or a Lib directory), then only the Lib[s] in that path will be opened; otherwise, a oaLibDefList::openLibs() will be executed (which will cause an error if no lib.defs file is located in the default search).
- If the VIEW, CELL, or LIB is the character / or absent, then (respectively)
- The whole CELL is displayed
- The whole LIB is displayed
- the whole RTM is displayed, which may include one or more Libs depending on lib.defs processing
Some OPTIONs require a following VALUE argument, or have other quirks. There are two syntax choices for displaying options.
5.1 oaUtil [OA Translators] Front-End [New in v1.6.5]
If OAUTIL is included in the list of compile DEFINEs when the tool is built from source, si2dis will use the same syntax used for the OA translator tools. With this syntax, every command line argument must either be an -option keyword, or have one immediately preceding it (separated with whitespace), though not all option keywords require a following value:
si2dis [ [OPTION [VALUE]] ...]
The OA util package is not set up for reuse of options on the command line. If multiple instances of the same option occur, oaUtil will ignore all but the last one. Hence, in the following example, only the last .si2oadoptions setting will take (i.e., the maxcollentries setting will be ignored):
make run INPUT="-o maxcollentries=0 -o output=console -lcv Lib/Sample/schematic"
This is appropriate for almost all options; however, it may be desirable to set multiple option overrides to the .si2oadoptions on the same command line. The si2dis option processing enables this by defining the value of the -option keyword to be one or more name=value pairs, separated by blank[s]:
make run INPUT="-o 'maxcollentries=0 -o output=console' -lcv Lib/Sample/schematic"
5.1.1 Options to Control RTM Subset for Display
If neither -lcv nor -lib is specified, the entire Session is displayed. -lcv Lib[/Cell[/View]] Specify the logical oaLib, oaCell, and oaView info (enabling command-line completion). Lib, Cell, and View args must not be used with -lcv. The -libdefs argument may be specified along with this option. -l | lib Lib name Specify the logical Lib name to display. -c | cell Cell name Specify the logical Cell name to display. -v | view View name Specify the logical View name to display.
-libDef Lib directory | lib.defs path Specify either the lib.defs path to use for openLibs().
-t | tech (new in 1.6.3) Display the Tech in the indicated Lib instead of anything else there. -dmd (new in 2.1) Display the DMData in the DMContainer indicated by the lcv (or related) options instead of anything. -dmdskip (new in 2.1) Skip traversal of any DMDatas.
5.1.2 Additional Help Info
-h | help Print this help message and quit (ignore all remaining args)
The following console message options do not propagate to the verbose setting of Si2oaD. Use the -o option (below) to set the Si2oaD verbose value via command line. Note that -q and -d are not mutually exclusive.
-q | quiet (new in 2.1) Suppress oaUtil (OA translator) tool header stars and trailer summary stats. By default, oaUtil messages are on. The -q must be used to turn them off. This option does not affect how si2dis debug messages are printed. Only the -d option sets si2dis informative messages. -d | debug (new in 1.6.3) Print extra progress and diagnostic (debug) information. By default, no extra debug messages will print. The -d must be used to turn them on. This option does not affect the messages printed from the oaUtil library. Use -q to suppress oaUtil messages.
5.1.3 .si2oadoptions Manipulation
-o | option NAME=VALUE[ NAME=VALUE]*
The next argument must be one or more NAME=VALUE pair[s] where the
* NAME is a legal Si2oaD option name
* VALUE is the value to assign to it
* multiple pairs are separated by spaces [blanks]
EXAMPLES: si2dis -option maxcollentries=1
si2dis -o verbose=3
-r | read OPTIONFILE_PATH
The next argument must be a path to a file of options. Without -r,
* a read of ./.si2oadoptions will be attempted;
* then $HOME/.si2oadoptions if that fails;
* the default options values will be used both fail.
-w | write OPTIONFILE_PATH
Write the current default options to OPTIONFILEPATH.
-r | regex REGEX_pathExpression
The next argument must be a regex. EXAMPLES:
* With the oad option casesensitive=t, this will not match RouteNet2:
si2dis -x "Block ScalarNet=routenet[246]*" Lib Sample schematic ../sample/LibDir
* Adding the i flag in front of the regex string will match it:
si2dis -x "+iBlock ScalarNet=routenet[246]*" Lib Sample schematic ../sample/LibDir'
5.1.4 Inherited oaUtil Options
Other command line processing semantics match those of the oaUtil classes (since they are the classes being used in this flavor). For example, options inherited from App<CommonOptions> include:
-logFile file-name Output messages will be copied to the specified file-name -noInfo msgIds Suppresses the specified WARNING messages. -noWarning msgIds Suppresses the specified INFO messages. -templFile file-name Input template -v Prints tool, format, and library version information. -version Prints tool and format version information.
5.2 Examples
A few examples the use various command line argument combinations follow below:
5.2.1 Help
A simple reminder of the various command-line arguments can be produced on the console by running,
make run INPUT="-help"
5.2.2 Debug
Adding -debug will produce additional messages that can help understand how the options are being processed providing insight into why the display may not be behaving as desired.
make run INPUT="-debug -lcv myLib/myAnd2/myAbstract -libDef /home/Data/Lib1/lib.defs"
5.2.3 Options File
The -read argument is used with a (relative or absolute) path of a valid OAD options file. This file must be in the same format as a file created by the -write argument, though only the option names and values to be changed need be included in the file. When an options file is read in this fashion, any values read in it will overwrite those set by the default .si2oadoptions or the default options file.
make run INPUT="-read origSi2oadoptionsFile -option xlstype=browser -lcv myLib/HalfAdder/netlist"
5.2.4 Regex
Regular expression filtering on Object Type and name may be included (prior to the Lib name argument) using the -x option followed by a pathExpression (section 6):
make run INPUT="-x pathExpression LIB CELL VIEW"
5.2.5 Dump an Entire OpenAccess Design to XML
If you want a text dump of the design, change the following options in the .si2oadoptions file. You may find it convenient to copy your ~/.si2oadoptions file to the current working directory, and edit that file.
output console # Send output to stdout rather than a web browser xsltype none # Skip XSLT transformation just to save time maxownerlevels 0 # Max owner chain depth to display (0 shows all data) maxcollentries 0 # Max collection entries to display at a time (0 shows all)
Select a design that is not too large, and run si2dis on it:
si2dis -lcv designLib/blockHead/layout > blockHead.dump.xml
Then parse or view the resulting XML file blockHead.dump.xml.
5.2.6 Option Examples (make)
These use the -lcv option making command-line completion on the path easier. The force use of a specific lib.defs file:
SI2DIS_NOPROMPT=1 make run INPUT="-v -lcv Lib// ../route/lib.defs" # Displays Lib SI2DIS_NOPROMPT=1 make run INPUT="-v -lcv Lib ../route/lib.defs" # Displays Lib
Without NOPROMPT, code assumes you want to specify L/C/V interactively if you leave one or more out.
Rest of these use default lib.defs (i.e., first in cwd then in $HOME)
make run INPUT="-v -lcv Lib/Sample " # Queries for View name SI2DIS_NOPROMPT=1 make run INPUT="-v -lcv Lib/Sample " # Displays Cell
Instead of -lcv option
make run INPUT="-v Lib Sample" # Will query for View (entering / will display Cell only)
SI2DIS_NOPROMPT=1 make run INPUT="-v Lib Sample" # Will NOT query for View (displays Cell only)
SI2DIS_NOPROMPT=1 make run INPUT="-v Lib Nand " # Displays Cell using default lib.defs
make run INPUT="-v / / /" # Displays Session
make run INPUT="-v " # Queries for Lib name; if / then displays Session
SI2DIS_NOPROMPT=1 make run INPUT="-v " # Displays Session
SI2DIS_NOPROMPT=1 make run INPUT="" # Displays Session
make run INPUT="-v -t Lib" # Displays Tech for Lib
make run INPUT="-v -t Lib Sample" # Displays Tech for Lib (Cell name ignored)
make run INPUT="-v -t -lcv Lib " # Displays Tech for Lib (Cell name ignored)
make run INPUT="-v -t -lcv Lib/ " # Displays Tech for Lib (Cell name ignored)
make run INPUT="-v -t -lcv Lib/Sample " # Displays Tech for Lib (Cell name ignored)
