OpenAccess Wiki for Public View/Login Edit

From oacwiki

Understanding Si2OAD's design criteria and how it works can helpful when trying to solve problems using the tool, cope with its limitations, or customize it for different site configurations and environments.

1 Requirements

Practical use case issues drove both the management of the tool development activities and the technical details of the implementation.

1.1 Project

For consistency with the spirit of OpenEDA in general, efforts have been made to

• Encourage participation across the OA Community
  • Close leadership by the WG has helped broaden requirement inputs and testing.
  • Si2 development of the prototype under WG guidance minimized IP encumbrances while providing a vehicle for distributing the support burden.
  • Making source available will (hopefully) provide a vehicle and the means for on-going support.
  • Staging the WG activities under an OpenEDA project umbrella, with accompanying flyers, as well as on-line, and in-person demos for the tool in various stages, has helped stimulate broader interest and cooperation from more member companies.
• Minimize development time and cost.
  To support evolution of requirements driven by WG feedback, rapid prototyping of new features was desired. This drove reuse of existing technology wherever possible:
  • XML, a mature cross-industry syntax with extensive cross-industry support to leverage of existing and free parsing and rendition tools.
  • Publicly available browsers for interactive display (as opposed to a custom GUI)
  • XSL to bridge the gap between XML and browser HTML
  • Javascript to provide active an interface

1.2 Technical

Specific use case goals drove development of features to

• Enable developers to "see" design data easily to help spot tool bugs and database problems. This led to support for a human-readable representation suitable for both batch and GUI uses, a format that lent itself to easy assimilation, with a structure that mapped closely to the RTM in which an OA programmer has to live.

• Allow use of the tool with existing application executables. Commercial tools are typically not available in source or as unlinked binaries. The LD_PRELOAD (8.2.1) technique makes it possible to debug using the OA data, even without access to the tool code. In addition, shared object "bundling" (8.2.2) has also been successfully used (which would work on platforms that do not support LD_PRELOAD).

• Avoid altering the RTM. Bounding Box calculations can be switched off. States of master relationship binding, as well as parasitics loading, are preserved, and selectively processed dynamically on a temporary basis. Option settings also allow such RTM changes on an automated basis.

• Minimize impact on memory allocation and performance. As much as possible, the code attempts to pass model information directly from traversal to output, without requiring large caches of intermediate data and look-ahead processing. Regex processing, however, breaks this goal because it is not possible to know in advance if data down in an owner hierarchy will be selected until it is accessed.

• Support both batch export and interactive, point-and-click renditions.

• Use the public API to insulate against cross-release changes to the OA Reference Implementation. The public API has been used for all design data access except in two cases:
  • AppDef access exploits API class implementation knowledge that all subtype AppDefs can be accessed directly from the underlying class oaAppDef. An oadAppDef class was derived directly from oaAppDef to get access to these private accessors. This enables processing of both Session and Object AppDefs with a single function of some 150 lines. Using only the public API would require a large number of templates be explicitly declared (one for each possible combination of Object Type and AppDef subtype) since it cannot be known until run-time exactly which combinations will be encountered in the data. This technique will break if the OA Reference Implementation ever implements an explicit accessor in an AppDef child class.
  • Iter caching (to support incremental loading of Collections, a few Objects at a time) exploits the knowledge that the API implementation uses a common oaBaseIter class destructor. Using only public API methods would require coping explicitly with every possible template type of Iter that could be involved in user data Collections. This technique will break if the OA Reference Implementation ever implements an explicit destructor in an Iter child class.

Other technical requirements were considered and even investigated, but ultimately discarded. For example, automating the generation of the OAD code was initially deemed desirable. In fact, some legwork was performed studing automated code generation from a model, for example, with a commercial UML tool (like Rational Rose or Argo). However, first a complete UML model, along with all its constraints, would have to be drawn – itself a reasonably time-consuming task. Since such automated generation often produces a clunky result, significant tweaking of the output was likely to be needed. Though such a UML model would undoubtedly be reusable, since it was not clear that OAD would even be that useful to OA developers and engineers, the WG did not want to undertake a significant effort as a prerequisite to even the first line of useful debugging code.

2 Linking to an Executable

There are a couple of techniques for making the Si2oaD symbols (produced by the compiler) available to a debugger so it can call the OAD interface functions – even though that library was not linked in when the application to be debugged was created.

2.1 LD_PRELOAD

The current technique implemented in the `make oad` target causes a .gdbinit file to be created that lists for LD_PRELOAD the libsi2oadebug.so and the list of OA shared libraries (either dbg or opt versions, whatever is set in makefile.defs). Note, however, that this technique may not be portable to all platform/compiler combinations.

2.2 Bundling Shared Libraries

An alternative technique that may be more portable to other development platforms uses the linker to "bundle" the Si2oaD library with one of the OA shared libraries – one that is required no matter how limited a tool's use of the API might be, such as liboaCommon.so. The resulting "Trojan horse" version of the OA shared lib could then be located in a different directory from the one holding the OA libs. That directory would be placed prior to the main OA lib/ directory on the LD_LIBRARY_PATH so that the bundled lib is accessed first during the dynamic loading process, thereby pulling in the oad() symbols and causing the necessary static initializations for use by the debugger. Figure 1 illustrates this concept and the corresponding LD_LIBRARY_PATH would be set to something like,

$ToolDir/:OAD/lib:$OA_ROOT/lib

This technique has been tested successfully on Linux and Solaris platforms; however, it is not currently being used in the distribution makefiles, which instead use the LD_PRELOAD technique.

3 Output Syntax

3.1 XML

Some aspects of the design of the raw XML output syntax are atypical of most SGML/XML markup styles. The OAD XML relies heavily on attributes and limits element use to represent containment relationships in the OA model. The tag dictionary is large with names that are part of the familiar OA model vocabulary:

• Attribute names generally match the names of OA attribute accessor functions or formal argument names (e.g., when passed by reference) of OA classes.
• Element names are the names of
  • classes
  • Collections

This design was driven by extensive testing which led to the following goals:

• maximize readability
• minimize tag overhead to reduce output volume and I/O time, especially for large designs
• correlate tag vocabulary as much as possible to the OA model terminology

Eliminating generic and redundant markup accomplishes these goals. So using what would be an enormous number of generic tag identifiers with the OA terminology as the element contents (as in the following sample) has been avoided:

          NOT this way!

<OBJECT id='0x1234'>
  <NAME>oaScalarNet</NAME>
  <ATTRIBUTE><NAME>SigType</NAME><VALUE>oacClockSigType</VALUE></ATTRIBUTE>
  <ATTRIBUTE><NAME>isGlobal</NAME><VALUE>true</VALUE></ATTRIBUTE>
  ...
  <OWNS>
    <COUNT>35</COUNT>
    <CLASS>
      <NAME>oaScalarTerm</NAME>
      ...
      </CLASS>
    <CLASS>
      <NAME>oaScalarTerm</NAME>
      ...
      </CLASS>
    ...
    </OWNS>
  </OBJECT>

Instead, the OAD syntax compresses this into the following style:

<oaScalarNet id='0x1234' sigType='oacClockSigType' isGlobal='t' ... />
  <terms O='' count='35'>
    <oaScalarTerm>...</oaScalarTerm>
    <oaScalarTerm>...</oaScalarTerm>
    ...
    </terms>
  ...
  </oaScalarNet>

Features of the output that make this style possible include the following:

• Attributes are broken out of the main Object tag only when they consist of multiple components of information, for example, the parent Design attribute of a DesignObject:

<parent design='#0xb6f2f992' lcv='Lib/Sample/schematic'/>

• In almost all cases, attribute names taken from accessor functions in the OA model are unique. For rare cases that could end up as multiple attributes of the same name on the same element, a slight rename of the attribute was chosen instead of forcing both attributes out into multiple sub-elements.
• The only attribute with DTD-standard semantics (used for oaObject handles) is “ID”. IDREF candidates were all assigned model-specific names, like 'refs', 'usedInDBs', 'master', etc.

Since attribute names were taken from accessor function or formal function parameter names, whitespace could not normally occur in them. Invented attribute names composed of multiple words simply concatenate the words using embedded capital letters; for example:

hasObjectCG='f'

Attribute values typically also do not have whitespace and follow the same rule, like,

type='rowHeaderDataType'

A few rare attribute values do include embedded whitespace, which is rendered as-is, requiring post processing (like XSLT) to preserve this. Examples include date/time values:

readIn='Thu May 15 16:20:00 2008'

3.2 HTML

XSLTransformation uses the HTML output method to generate an HTML version of the raw XML.

<xsl:output method="html" />

A CSS style sheet assigns display format rules. Block level tags follow normal HTML semantic conventions:

• <SPAN style=' '> The wrapper used by si2oadheader.js Javascript to manage dynamic collapse/expand of Object containers and Collection containers by setting the style attribute's display setting in response to click events on the browser GUI.
• <SPAN class='x' > A main container element.
• <SPAN class='n'> An element with no children (such as an attribute with compound values).
• The inside wrapper for the container. At runtime, th

Inline tags are selected for brevity and (except for the A tag) have the non-standard semantics:

• A – A standard anchor used for wrapping 'id' attributes with HTML ID target semantics.
• B – The wrapper for an oaObject name
• I – The wrapper for the +/- character for expand/collapse actions
• U – The wrapper for attributes of an Object or Collection

Typical HTML around an Object (such as an oaDesign) might look as follows:

<SPAN style="display:none">
  <SPAN class="x">
    <I>+</I>
    designs
    <U> count=4</U>
    <SPAN style="display:none">
      <SPAN class="x">
        <I>+</I>
        <B>oaDesign</B>
        <U> name=Lib/Sample/schematic mode=r
          <A ID="0xb6f2f992">id=0xb6f2f992</A>
          </U>
        ...

4 TCL Interface

The si2dis/Makefile that produces libsi2oadebug.so also creates a Tcl interface to it called, si2oadtcl.so. This is created using SWIG.

The runtcl make target in si2distest/ shows how to use this code.

At this time, only two of the oad() interface functions are wrapped by the si2oadtcl.i file:

• oad $objectVariable
• oad “command” “options”