Si2oaD/Use Cases
From oacwiki
Contents |
1 Debugging
The original motivations driving creation of Si2oaD arose from the need for a complete and readable view of RTM/persistent data to help
- debug application failures,
- understand customer data problems, and to a lesser extent,
- verify the OA implementation.
1.1 Interactive Display of Run-Time Data
The Si2oaD binaries can be used with any application and within a debugger (such as gdb or dbx) session. At any breakpoint any of the Si2oaD interface functions can be invoked:
The testcase, test1.cpp, in the directory si2distest/ builds on the example design data in sample/ directory, creating enough oaObjects to provide a good walk-through of the display features. The testcase illustrates use of the Si2oaD libraries with any application without having to touch the application source code.
A visual representation of the data being created by application code can help flatten the learning curve for engineers learning the OA model for the first time, as well as experienced OA hackers delving into some corner of the API for the first time.
2 Embedded oad() Calls
This utility and its Makefile illustrate how to link explicity with the Si2oaD libraries to enable embedding oad() calls in any application code.
Any application can include the Si2oaD interface header to enable use of all oad() interface functions directly.
#include "si2oad.h"
Once an application is linked with Si2oaD libraries, the oad() interface functions may be invoked directly by the application code to provide snapshots of any subset of the OA RTM. Such snapshots can then be post-processed for various purposes.
3 Event Tracing
The observer option (4.1.4) provides a hook for insertion of arbitrary user code into the OA RTM.
4 Post-Processing
The ASCII output format lends itself to automated post processing. Many mature commercial and free tools exist to manipulate XML – parsers, XSL transformers, editors, etc.
4.1 Regression testing
A "golden" snapshot of the design data resulting from a particular test run of an application under testing can be saved for use with simple ASCII diff tools as the application evolves. However, there are a few problems that will get in the way
- Order – Iteration order of owned Objects is not guaranteed by the oaIter classes. The alwayssort option, combined with a sort dll (the same one for both runs, of course) can fix this.
- TimeStamps – The main containers (Design, Tech, etc.) all have TimeStamps, as well as other time/date attributes (createTime, readInTime, lastSavedTime, etc.) that would need to be filtered before a diff.
- Path names – Some pathName attributes may include a root directory path prefix that differs from run to run, depending on where the current directory is at the time.
- OIDs – The output deliberately includes the actual run-time handles for oaObjects. These will match only coincidentally on successive runs. One way to handle this problem is to delete all the handles prior to running diff. The diffemh target in makefile.defs illustrates one way to accomplish this using sed (assuming that the "golden" output already had this done on it):
sed "s/<0x[0-9abcdef]*>/<>/g" $(PROG).out >$(TMPFILENAME) if $(DIFF) -w $(TMPFILENAME) Solution/$(GOLD).out ;\
- File names – Some OA data, such as parasitics and DMFiles, are represented in some DM systems as separate filesystem entries, each with a unique identifier encoded into its name. The construction of such identifiers depends on the DM system, and so can differ from run to run.
- Output streams – Debug or status information can be interspersed in output data in unpredictable ways.
- Observers – Observers that print such data can fire at various times.
- Threads – Debug output (with verbose enabled) in different threads can show up in different places.
4.2 Analysis
All attributes and relationships among data objects are available in the XML output. Unexpected artifacts in the output can aid in the detection of bugs in an application or errors in the data.
4.3 Reformatting
The si2oad.xsl transform illustrates one reformatting use case. This XSLT converts the XML description of the design data into HTML, adding Javascript for active content features. The result can be displayed in a browser to enhance the visualization of the model.
XSL (or a program written in any language) could be used to filter or change the appearance the resulting output. Such a transformation could be performed dynamically as the output is generated.
5 Training
Si2oaD visualization of a complete OA model can help an engineer in a variety of ways, both for
- designs stored on disk
- data changing dynamically in an application at run-time.
In early encounters with the OA API, Si2oaD's rendition of design data can significantly aid the learning process. Even for those reasonably familiar with the model, a complete display of its contents at different stages within the context of a real problem-solving expedition can continue to provide instruction regarding additional levels of OA semantic detail.
