\documentclass[11pt]{report}

\usepackage{alltt,color,fullpage,psfig}

\newcommand{\version}{1.0}

\begin{document}

\title{
\textbf{SAVANT Programmer's Manual} \\
(Documentation for version \version)}

\author{
\emph{Dale E. Martin} and \emph{Philip A. Wilsey} \\
Computer Architecture Design Laboratory \\
Dept of ECECS, PO Box 210030 \\
Cincinnati, OH  45221--0030 \\
\texttt{savant@ececs.uc.edu}
}

\date{}

\maketitle

\vspace*{6in}

\noindent
Copyright \copyright 1995-1999 The University of Cincinnati.  All
rights reserved. 

\bigskip

\noindent
Published by the University of Cincinnati \\
Dept of ECECS, PO Box 210030 \\
Cincinnati, OH  45221--0030 USA 

\bigskip

\noindent
Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

\medskip
\noindent
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

\medskip
\noindent
Permission is granted to copy and distribute translations of this manual
into another language, under the above conditions for modified versions.

\newpage

\tableofcontents

\chapter{Introduction}

SCRAM is a VHDL analyzer and extensible environment for CAD tool
backend development.  VHDL descriptions are analyzed and stored in the
SAVANT intermediate form (IF), which is comptaible with the Advanced
Intermediate Representation with Extensibility (AIRE).  Provisions to
support the insertion of backend CAD tools have been provided.  More
precisely, a technique for structuring and instantiating the nodes of
the IF built by SCRAM has been developed that allows the CAD tool
builder to easily insert additional capabilities into the IF
structure.  The specific technique is described in the following
section.  The effect is the construction of an extensible class
structure for the SAVANT IF as outlined in the SAVANT Overview
document.

The SCRAM parser is constructed as an LL(2) grammar using the Purdue
Compiler Construction Tool Set (PCCTS) parser generator (many thanks
to Terence Parr, Hank Dietz, Will Cohen, and to Tom Moog who has
continued improving PCCTS 1.33).  PCCTS is available at
{\tt http://www.polhode.com/pccts133mr.html}.  SCRAM has been developed
in C++ using GNU's EGCS 1.1.1 compiler.  Effort has been made to
maintain compatibility with GNU's g++ 2.7.2 for the 1.0 release of
SAVANT - future versions of SAVANT most likely will use features found
only the the newer versions of the the GNU EGCS compilers, such as
exceptions and/or namespaces.

\chapter{Introduction}

\section{Introduction to SAVANT}

\begin{description}
  
\item[SAVANT?]  Standard Analyzer of VHDL Applications for Next-generation
  Technology.
  
\item[Who?]  MTL Systems and the University of Cincinnati.  Funding by
  Wright Labs, SBIR Phase II.
  
\item[What?]  Create a freely available, extensible VHDL Analyzer.
  Provided value added benefit and market.
  
\item[Why?]  Stimulate integration of VHDL technology into the CAD
  research community.

\end{description}

\newcommand{\Cpp}{C$^{_{++}}$}

\section{The Software Components of SAVANT}

\begin{description}
\item[SCRAM:] a VHDL analyzer
\item[Extensible classes:] to build intermediate forms for
    \begin{itemize}
    \item IIR from the AIRE spec

    \item FIR from the AIRE spec \footnote{FIR support has been
    suspended and the existing code removed from SAVANT due to an
    incomplete specification at the time that the implementation was
    being done.  FIR support could occur in the future if resources
    become available.  Patches of the existing FIR implentation which
    are no longer being maintained could be made to interested parties
    on request.}

    \end{itemize}
\item[Extension classes:] \
    \begin{itemize}
    \item transmute: eliminating redundant structures in the IIR
    \item publisher: outputting VHDL and \Cpp\footnotemark
    \item archiver: extensions to read/write FIR files to/from IIR trees
    \end{itemize}
\end{description}


\footnotetext{The development of the \Cpp output is sponsored by DARPA.}

\section{Software Availability}

\begin{itemize}
\item Copyrighted by the University of Cincinnati
\item Freely Redistributable under the terms of the GNU Public Library License. (LGPL)
\end{itemize}

\section{The Intermediate Forms}

\noindent
\textbf{AIRE:} Advanced Intermediate Representation with Extensibility

\begin{enumerate}
\item Formats:
    \begin{description} \item[IIR:] in-memory intermediate
    representation \item[FIR:] file intermediate representation
    \end{description}

\item
Jointly developed by:
\begin{small}
\begin{itemize}
\item University of Adelaide (Australia)
\item DA Solutions Ltd (UK)
\item FTL Systems, Inc. (USA)
\item MTL Systems, Inc. (USA)
\item University of Cincinnati (USA)
\end{itemize}
\end{small}

\end{enumerate}

\newpage

\noindent

\begin{minipage}{6in}
\psfig{file=uc-projects.ps,angle=270,width=6in,silent=}
\noindent
\begin{scriptsize}
\copyright 1995-1999 The University of Cincinnati.  Reprinted with permission.
\end{scriptsize}
\end{minipage}

\section{AIRE: Current Status}

\begin{itemize}
\item IIR:
    \begin{itemize}
    \item Draft design complete
    \item Implementations by UC, FTL, and other parties
    \item Extensible object-oriented design
    \end{itemize}
\item FIR:
    \begin{itemize}
    \item Draft design in progress
    \item Implementations under-development
    \item Extensible object-oriented design
    \end{itemize}
\item EIA standardization in progress
\end{itemize}


\section{SCRAM: Current Status}

\begin{itemize}
\item LL(2) grammar
\item Flex lexer, ANTLR (from PCCTS) parser generator
\item Parsing: complete language coverage
\item IIR node construction: complete
\item Type checking: implemented, tested and validated
\item Overloaded name resolution implemented
\end{itemize}


\section{SAVANT Implementation of AIRE: Current Status}

\begin{itemize}
\item IIR implementation complete
\item FIR implementation suspended
\end{itemize}


\section{Extensibility in SAVANT}

\begin{itemize}
\item Achieved by user added derived classes to IIR/FIR
\item Allow addition of data and methods to all AIRE classes
\item Provide user full benefits of object-oriented programming
\end{itemize}


\section{Class Relationships Supporting Extensibility}

\psfig{file=savant-if.ps,angle=270,width=6.5in,silent=}


\section{Transmute: Current Status}

\begin{itemize}
\item Base rewriting are all implemented 
\item Operational on a node-by-node basis (integrated with publish)
\item Available for use by extension classes
\end{itemize}


\section{Record/Playback: Current Status}

\begin{itemize}
\item Initial implementation of FIR class nodes completed in 1998
\item Implementation suspended due to incomplete specification
\item Specification is reported to be complete, and if resources become available
it's possible that FIR support could be reintegrated
\item Library support in SAVANT currently accomplished through VHDL publishing and reparsing
\end{itemize}


\section{Publish: Current Status}

\begin{itemize}
\item VHDL regeneration complete
\item C++ for TyVIS operational and complete
\end{itemize}

\section{Auxiliary Support Tools}

\begin{itemize}
\item Flex: lexer generator
\item PCCTS: parser-generator
\item C++ compiler
\item Assorted unix tools, e.g., make
\end{itemize}


\section{Project Web Sites}

\begin{itemize}
\item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/savant/}
\end{itemize}


\section{Related Web Sites}

\begin{itemize}
\item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/aire/}
\item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/quest/}
\item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/tyvis/}
\item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/warped/}
\item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/rassp/}
\end{itemize}


\chapter{SAVANT INSTALLATION}

\section{Installation}

\begin{itemize}
\item Requirements
    \begin{itemize} \item Resources \item Tools \end{itemize}
\item Where to get it
\item Installation Procedure
\item Updating Your Distribution
    \begin{itemize}
    \item Via patches
    \item CVS import
    \end{itemize}
\end{itemize}


\section{Resource Requirements}

\begin{description}

\item \textbf{Approximate Disk Space Requirements} (for Linux and Solaris,
varies with OS and compiler)

    \begin{itemize} 
	\item 10M of Disk space for distributed source code or binaries 
	\item 70M of Disk space for compilation 
	\item 18M of Disk space for executable (with debug information) 
	\item 3M of Disk space for executable (without debug information)
    \end{itemize}

\item \textbf{Virtual Memory} 

    \begin{itemize}
    \item At least 40M of virtual memory (for compilation).
    \end{itemize}

\end{description}


\section{Tool Requirements}

\begin{description}
\item[tar] Gnu tar version 1.2 is known to work
\item[gunzip] Gnu gunzip version 1.2.4 is known to work
\item[Make] Gnu make version 3.77 is known to work
\item[Lexer] Flex version 2.5.4 is known to work
\item[Parser Generator] PCCTS version 1.33MR12b is known to work
\item[C++ compiler] A full featured C++ compiler is required.  Known to
work: 
    \begin{itemize}
    \item g++ version 2.7.2 (and later)
    \item EGCS g++ version 1.1.1
    \item Sunpro C++ version 4.1
    \item Digital Unix cxx C++ compiler
    \end{itemize}
\item[Operating System Environment] Unix.  Known to work:
    \begin{itemize}
    \item Linux versions 2.0 and 2.2
    \item Solaris 2.6
    \item Digital Unix
    \end{itemize}
\end{description}


\section{Where to get it}

\begin{description}
\item[SAVANT:] \
    \begin{itemize}
    \item Source code, Debian Linux packages, and Solaris 2.6 packages\\ {\tt ftp://ftp.ececs.uc.edu/pub/users/dmartin/}
    \item Debian Linux packages - {\tt ftp://ftp.debian.org}
    \end{itemize}
\item[GNU Tools:] Make, Flex, g++, gnu tar, gunzip, and cvs
    \begin{itemize}
    \item {\tt ftp://prep.ai.mit.edu/pub/gnu/}
    \item {\tt ftp://gatekeeper.dec.com:/pub/GNU/}
    \end{itemize}
\item[PCCTS:] \
    \begin{itemize}
    \item {\tt http://www.polhode.com/pccts133mr.html}
    \end{itemize}
\item[Linux:] \
    \begin{itemize}
    \item {\tt http://sunsite.unc.edu/pub/Linux/distributions/} or
    \item {\tt ftp://ftp.yggdrasil.com/mirrors/sunsite/INDEX.html} or
    \item {\tt ftp://ftp.debian.org/pub/debian}
    \end{itemize}
\end{description}


\section{Downloading/unpacking Tips}

\begin{itemize}
\item Always use \textbf{binary mode} when downloading files with ftp.

\item SAVANT is distributed in a \textbf{gzip}'ed \textbf{tar}file.

\item
To uncompress the gzip'ed file {\tt foo.gz}, type:
    \begin{description}
    \item {\tt gunzip foo.gz}
    \end{description}

\item 
To unarchive a tar'ed file {\tt foo.tar}, type:
    \begin{description}
    \item {\tt tar -xf foo.tar}
    \end{description}

\item 
To unarchive a gzip'ed tar file {\tt foo.tgz}, type:
    \begin{description}
    \item {\tt tar -xzf foo.tgz}
    \end{description}

\item 
Suffixes can be cumulative: a gzip'ed tar file may be named: \\
{\tt foo.tar.gz}, which is unpacked by
    \begin{description}
    \item {\tt gunzip foo.tar.gz}
    \item {\tt tar -xf foo.tar}
    \end{description}

\end{itemize}


\section{Unix Environment Variables}

\begin{itemize}

\item
Environment variables exist in the shell to pass information to
application programs.  

\item
SAVANT uses two environment variables ({\tt PCCTSROOT} and
{\tt SAVANTROOT}) to determine the location of header files and
libraries.  

\item
Depending on the shell you use, there are different methods for setting
environment variables.  See your shell documentation for details.

\end{itemize}


\section{Setting Environment Variables \\
\textrm{(For the shells: {\tt bash} and {\tt sh})}}

\begin{alltt}
set FOO=/home/john-doe
export FOO
\end{alltt}


\section{Setting Environment Variables \\
\textrm{(For the shells: {\tt csh} and {\tt tcsh})}}

\begin{alltt}
setenv FOO /home/john-doe
\end{alltt}


\section{SAVANT Environment Variables}

\begin{description}

\item[PCCTSROOT:] This variable specifies the location of the header
files included with {\tt pccts}.  Needed to compile SAVANT.

\item[SAVANTROOT:] This variable specifies the the top level directory
of the SAVANT distribution.  Needed to compile SAVANT.  Need for the
execution of SCRAM if not installed in a ``standard'' subdirectory,
such as {\tt /usr} or {\tt /usr/local}.

\end{description}


\section{Preparing SAVANT for compilation}

\begin{enumerate}

\item
Set the environment variables {\tt PCCTSROOT} and {\tt SAVANTROOT}.

\item
The SAVANT distribution is shipped with a configuration script to
generate a Makefile for your environment.  This script is named
{\tt configure} and is in the directory {\tt savant/src}.  To
configure the system, execute the following commands:

\begin{alltt}
cd savant/src
./configure
\end{alltt}

\end{enumerate}


\section{The {\tt configure} script}

\begin{itemize}

\item
The {\tt configure} script will generate two Makefiles -
{\tt Makefile} in the {\tt savant/src} directory and {\tt Makefile.common}
in the {\tt savant/lib} directory, from the files
{\tt Makefile.in} and {\tt Makefile.common.in} respectively.

\item
The script searches for a C++ compiler on your system.  If the
compiler you want to use is not in the list the script knows about, or
if it locates a compiler other than the one you want to use, you can
explicitly name a compiler in the environment variable
{\tt CXX}.  This variable only needs to be defined while the script
is running; it can be unset after the script has finished.

\end{itemize}


\section{Building Dependencies}
\noindent
To build the SAVANT system, the {\tt make} utility is used.
{\tt make} requires a list of dependencies to be generated into the file 
{\tt .depend}. To generate these dependencies, issue the following commands:

\begin{alltt}
cd savant/src
make depend
\end{alltt}

If only life was so simple.  The generation of dependencies has been
the main problem that users of SAVANT have asked the developers about.
Initially SAVANT's Makefiles were written to call {\tt makedepend}
which is actually part of the X Window system.  Eventually, the large
number of files in the intermediate caused the ``stock''
{\tt makedepend} to fail.  One solution to this problem is to
recompile {\tt makedepend} with some {\tt \#define}s increased -
see the file {\tt INSTALL} for details.  This isn't that simple to
do since the program includes many files from the X Windows source - a
full X source distribution is required.  The developers responded to
this problem by shipping binaries for the expanded {\tt makedepend}
for some common platforms with the source archive.  This solution
works if you're using a supported platform.  

Another approach is to use {\tt g++} to generate dependencies.  The
configure script looks for {\tt g++} specifically for this purpose
(even if you've specified another compiler in the {\tt CXX}
environment variable).  However, the developers have experienced
problems with this method - it appears that either {\tt make} or
{\tt g++} has a bug in it.

The file {\tt savant/lib/Makefile.common\{.in\}} defines a variable
{\tt MAKEDEPEND}.  The configure script sets it one of two ways:

\begin{itemize}

\item  {\tt MAKEDEPEND=-rm -f .depend; g++ -MM -MG \$(MDFLAGS) \$(CPPFLAGS)
\$(MAKEDEP\_SRCS) \\
> .depend } 

or

\item {\tt MAKEDEPEND=-rm -f .depend; ../bin/makedepend.\$host\_os -f- --
\$(MDFLAGS) \\ 
\$(CPPFLAGS) -- \$(MAKEDEP\_SRCS) > .depend }

\end{itemize}

In the second example shown above, {\tt \$host\_os} will be replaced
with the OS portion of the output from {\tt config.guess}.  For a
most Linux machines, for example, the full binary name would be
{\tt makedepend.linux-gnu}.  These examples are provided to allow
the reader to determine the best solution for dependency generation
available to them, and to provide them with the capability to insert
their own solution into the Makefile.

\section{Notes about Building Dependencies}

\begin{enumerate}

\item 
it's a good idea to build dependencies any time you run the {\tt
configure} script for the first time.

\item
anytime there is a change made to a source file in the SAVANT system
involving a {\tt \#include}, this procedure needs to be performed.

\end{enumerate}

\section{Compiling the system}

\noindent
To compile the system, issue the commands:

\begin{alltt}
cd savant/src
make
\end{alltt}

\chapter{CVS and SAVANT Updates}

\section{Source Code Control}

\noindent
Code control systems have many benefits for software developers.  CVS
is one example of such a system. Its features include:

\begin{itemize}
\item Support for Concurrent Software Development
\item A common Central Repository of the Software
\item Version Tags, Revision numbers, and Timestamps
\item Support for off-site Importing and Exporting of revised versions
\item Automatic Inclusion of Log Messages
\end{itemize}

\noindent
The SAVANT software developers use cvs in a very concurrent and
complex setting.  It works very well for them, and they'd recommend it
to anyone doing any type of software development, large or small.

\section{Coordinating with SAVANT Distributions}

\begin{itemize}
\item cvs supports the {\tt import}ing of revised versions from a
    remote site
\item \textbf{Recommendation:} users of SAVANT will benefit from using cvs
    to manage their software for integration (by cvs {\tt import}) with
    revisions to the SAVANT software
\item Alternatives to cvs do exist, but will not be explained here or in
    the SAVANT distributed software.
\end{itemize}


\section{Creating a CVS Archive} 

\noindent
If this is the first CVS archive you have ever set up, first you will need
to set up an archive directory.  The archive directory can be specified by
the environment variable {\tt CVSROOT}.  Assume that
{\tt my\_cvs\_archive} is to be the name of the the archive directory.
Then it's creation is achieved (in csh) by issuing the following commands:

\begin{alltt}
cd
mkdir my\_cvs\_archive
mkdir my\_cvs\_archive/CVSROOT
setenv CVSROOT my\_cvs\_archive
\end{alltt}



\section{Importing New Code into an Archive} 

\noindent
Importing your code for the first time.  For this example, our project
name is {\tt my\_project} and the initial revision of the code is in the
subdirectory {\tt work/src}.  We'll call our organization
{\tt savant\_geeks} and make this revision {\tt 1\_2}.

\begin{alltt}
cd work/src
cvs import my\_project savant\_geeks 1\_2
\end{alltt}

\begin{itemize}
\item cvs will invoke your default editor for entry of a log message
\item edit the buffer with the desired log message
\item save the buffer
\item exit the editor and the log message will be applied
\end{itemize}


\section{Explanation of the {\tt import} Command}

\noindent
The syntax for {\tt cvs import} is:

\begin{description}
\item {\tt cvs import [repository] [vendor-tag] [release-tags]}
\item where
    \begin{description}
    \item[repository] This is the name you want to give the project.
    There may be more than one repository per CVS archive, so they must be
    uniquely named.  Furthermore, when checking code out of the archive,
    it is placed in a directory with the same name as the repository.
    \item[vendor-tag] This simply names the authoring ``vendor''.
    \item[release-tags] This names any tags you would like to give the
    initial check-in.  Tags can be used later to retrieve specific revision
    of files.
    \end{description}
\end{description}



\section{Checking out a CVS module}

\noindent
After checking in the initial revision of your application, it is
important to check out a working copy from the archive.  This is done by
using the command 

\begin{description}
\item {\tt cvs checkout [module]}
\end{description}

\noindent
CVS will create a subdirectory with the same name as the module in the
current directory.  This is your working directory, and changes made to
the files in this directory do not affect the archive until they are
explicitly committed.

\section{Committing Changes to the Archive}

\noindent
Changes are committed to the archive using the command:

\begin{description}
\item {\tt cvs commit}
\end{description}

\noindent
The names of the files to commit may optionally follow the command.  If no
file names are given, CVS will recurse through all subdirectories, and
commit all files that have been modified since they were checked out of
the archive.

\noindent
\textbf{Notes:} 

\begin{enumerate}

\item
Each time files are committed to the archive your editor will be invoked
for a log message. 

\item
cvs commands operate implicitly on files in your current directory.

\end{enumerate}


\section{Adding Files to the Archive}

\noindent
New files to be added to the CVS archive must be explicitly added using
the {\tt cvs add} command.  For example, addition of the file
{\tt foo} 
using
the 

\begin{description}
\item {\tt cvs add foo}
\end{description}

\noindent
\textbf{Notes:} 

\begin{enumerate}

\item 
{\tt foo} can be a list of files.

\item
Each time file(s) are added to the archive your editor will be invoked
for a log message. 

\item
cvs commands operate implicitly on files in your current directory.

\end{enumerate}


\section{Removing Files from the Archive}

\noindent
To remove a file (\emph{e.g.,} {\tt foo}) from the archive:

\begin{enumerate}
\item remove the {\tt foo} from the working directory
\item issue the command: {\tt cvs remove foo}
\end{enumerate}

\noindent
\textbf{Notes:}

\begin{enumerate}

\item
CVS keeps deleted files available in case requests to checkout old
versions of the software are issued.

\item
CVS will refuse to delete a file that still exists in the working
directory.

\end{enumerate}


\section{Importing new SAVANT Releases into Your Archive}

\begin{itemize}

\item
If you are developing software using the SAVANT system, and a new
SAVANT release becomes available, the following steps can be used to
import the new release into your archive.

\item
For example to import a newly released version of savant (0.2.99d in this
example), into the CVS archived named {\tt testing} you would type:

\begin{alltt}
tar -xvf savant-v0.2.99d.tar
cd savant
cvs import testing dale v0\_2\_99d
[ type in log message when prompted ]
\end{alltt}

\item 
Syntax: \\
{\tt cvs import [repository] [vendor-tag] [release-tags]}

\end{itemize}


\section{Output Generated from CVS Commands}

\noindent
CVS will report file modifications as they occur, in the following format:

\begin{alltt}
U testing/src/aire/IIRBase/IIRBase\_ContextClause.hh
U testing/src/aire/IIRBase/IIRBase\_LibraryDeclaration.cc
M testing/src/aire/IIRBase/IIRBase\_LibraryDeclaration.hh
C testing/src/aire/IIRBase/IIRBase\_ComponentDeclaration.hh
\end{alltt}

\section{Meaning of the Output Generated by CVS}

\begin{description}
\item[U] This file was updated by the import.
\item[M] This file was modified by you.
\item[C] Both you and the off-site developers modified this file, and
    CVS was unable to automatically resolve the conflict. (the differences
    will be saved in the file and surrounded by 
    \begin{description}
    \item {\tt <<<<<<< working-filename}
    \item {\tt =======}
    \item {\tt >>>>>>> version-number}
    \end{description}

\end{description}

\chapter{The AIRE Standard}

\section{Introduction to the AIRE specification}

\begin{description}
\item[Who?] \ \\
Initiated by Wright Labs, FTL Systems, and the University of Cincinnati.

\item[What?] \ \\
Create a specification for a freely available, highly portable, extensible
VHDL intermediate form. 

\item[Why?] \ \\
To allow easy tool interoperability.

\end{description}


\section{AIRE Objectives}

\begin{itemize}

\item
Develop portable, memory-based and file-based representation of HDL
designs

\item
Permit free redistribution tools complying with the specification

\item
Permit free implementation of tools complying with the specification

\item
Permit interoperability and exchange of
    \begin{itemize}
    \item VHDL backend analysis tools
    \item VHDL libraries access utilities
    \item VHDL libraries
    \end{itemize}

\end{itemize}


\section{AIRE Fundamentals}

\noindent
Fundamental aspects of AIRE:

\begin{description}
\item[Object-Oriented] \ \\
The AIRE specification is presented as a class hierarchy.  \\
Each class has methods defined that implement its functionality.

\item[Portable Across Languages] \ \\
Allows implementation in variety of OO languages \\
Does not preclude implementations in non-OO language, \emph{e.g.,} C or
Ada 

\end{description}


\section{AIRE Overview}

\begin{enumerate}
\item Formats:
    \begin{description}
    \item[IIR:] in-memory intermediate representation
    \item[FIR:] file intermediate representation
    \end{description}

\item
AIRE is a working group under EIA.

\item
Scope: IEEE Std 1076--87 (VHDL 87), 1076-93 (VHDL 93) 1076.1 (Mixed
Signal), 1364 (Verilog as VHDL).

\item
Jointly developed by:
\begin{small}
\begin{itemize}
\item University of Adelaide (Australia)
\item DA Solutions Ltd (UK)
\item FTL Systems, Inc. (USA)
\item MTL Systems, Inc. (USA)
\item University of Cincinnati (USA)
\end{itemize}
\end{small}

\end{enumerate}


\section{AIRE Documents}

\begin{itemize}

\item Available in both HTML and postscript forms.
\item HTML version fully hyper-linked and X-referenced
\item Primary viewing sites:
    \begin{itemize}
    \item {\tt http://www.vhdl.org/vi/aire/}
    \item {\tt http://www.ftlsystems.com/aire/Index.htm}
    \item {\tt http://www.ececs.uc.edu/}\verb+~+{\tt paw/aire/}
    \item {\tt http://www.cs.adelaide.edu.au/users/vide/aire/}
    \end{itemize}

\end{itemize}


\section{AIRE Fundamental Data Types}

\begin{description}

\item[IR\_Boolean:]
an enumeration type defining values {\tt TRUE} and {\tt FALSE}.

\item[IR\_Character:]
the domain of values covering the ISO 8859-1 standard.

\item[IR\_Int32:]
a domain of discrete values covering the range \\
-2,147,483,647 to +2,147,483,647. 

\item[IR\_Int64:]
a domain of discrete values covering the range \\
-4,611,686,014,132,420,609 to +4,611,686,014,132,420,609. 

\item[IR\_FP32:]
representing the 32-bit floating point type in IEEE Std. 754.

\item[IR\_FP64:]
representing the 64-bit floating point type in IEEE Std. 754.

\item [IR\_Kind:] 
an enumeration uniquely qualifying each class.

\end{description}


\section{IIR Overview}

\begin{itemize}
\item Object-oriented, extensible data structure
\item No public data in base definition
\item Only public interface is by method invocation
\item Approximately 227 class definitions
\item Quasi-stable, current version: 4
\item Two implementations under development 
    \begin{itemize}
    \item Auriga: FTL Systems, Inc
    \item SAVANT: UC/MTL Systems, Inc
    \end{itemize}
\item Singlely rooted (at {\tt class IIR})
\end{itemize}


\section{Chief Design Requirements for IIR}

\begin{itemize}
\item Language Scope (coverage of 1976-87/93, 1976.1, 1364, Trial
  Implementation Draft of 1/24/97  Including Digital VHDL \& VHDL-AMS support)
\item Supportive of Multi-backend analysis tools
\item Portable
\item Extensibility
\item Efficiency
\item Support integration and product exchange
\item Security (offer support for IP)
\item Availability (non-proprietary, free or nearly free)
\end{itemize}


\section{Real Object-Oriented Definition}

\begin{itemize}
\item Other intermediates defined as OO, but in practice were not really OO
\item IIR is defined as an OO structure
\item IIR supports use as an OO structure
\end{itemize}


\section{Example of the Derivation Hierarchy}

\begin{description}
\item \
\begin{itemize}
\item IIR
    \begin{itemize}
    \item IIR\_DesignFile
    \item IIR\_Comment
    \item . . . 
    \item IIR\_SequentialStatement
        \begin{itemize}
        \item IIR\_AssertionStatement
        \item IIR\_BreakStatement
        \item . . .
        \end{itemize}
    \item IIR\_ConcurrentStatement
    \end{itemize}
\end{itemize}
\end{description}


\section{Constructors/Destructors}

\begin{itemize}
\item All constructors must have no arguments
\item No constraints on destructors
\end{itemize}


\section{Interior Classes}

\begin{itemize}
\item Some intermediate classes not directly instantiatable
\item \emph{e.g.,} IIR\_SequentialStatement
\item Interior classes are indirectly instantiated by instantiation of
    children
\end{itemize}


\section{The IIR Class Hierarchy}

\psfig{file=iir-extensible.ps,height=6in,silent=}


\section{Extensibility}

\begin{itemize}

\item Each IIR class is really a collection of 2 or more classes

    \begin{itemize}
    \item \textbf{IIRBase\_X}: root class containing all predefined public
    methods 
    \item \textbf{IIRUser\_X}: user class, void in base IIR definition
    \item \textbf{IIR\_X}: leaf class for this class (possible internal leaf)
    where \textbf{X} is a qualifier for a class in IIR
    \end{itemize}

\item Only leaf classes of non-interior classes are instantiatable \\
    (the derivation chain instantiates the respective parents)

\end{itemize}



\section{Example from the HTML definition of IIR}

\psfig{file=iir-seqStatement.ps,angle=270,width=6in,silent=}


\section{FIR Overview}

\begin{itemize}
\item Object-oriented, extensible data structure
\item Platform independent data formats to facilitate FIR library data exchange
\item Design in progress, current version: 3.0
\item Two implementations under development 
    \begin{itemize}
    \item Auriga: FTL Systems, Inc
    \item SAVANT: University of Cincinnati
    \end{itemize}
\item Singlely rooted (at {\tt class FIR})
\end{itemize}


\section{Chief Design Requirements for IIR}

\begin{itemize}
\item Language Scope (coverage of 1976-87/93, 1976.1, 1364)
\item Supportive of Multi-backend analysis tools
\item Portable
\item Extensibility
\item Efficiency
\item Support integration and product exchange
\item Security (offer support for IP)
\item Availability (non-proprietary, free or nearly free)
\end{itemize}


\section{Real Object-Oriented Definition}

\begin{itemize}
\item FIR is defined as an OO structure
\item FIR supports use as an OO structure
\item Design structure mirrors the class IIR definition
\item Unlike IIR, FIR's public interface is a data structure definition
\end{itemize}


\section{Example of the Derivation Hierarchy}

\begin{description}
\item \
\begin{itemize}
\item FIR
    \begin{itemize}
    \item FIR\_DesignFile
    \item FIR\_Comment
    \item . . . 
    \item FIR\_SequentialStatement
        \begin{itemize}
        \item FIR\_AssertionStatement
        \item FIR\_BreakStatement
        \item . . .
        \end{itemize}
    \item FIR\_ConcurrentStatement
    \end{itemize}
\end{itemize}
\end{description}


\section{The FIR Class Hierarchy}

\psfig{file=fir-extensible.ps,height=5.15in,silent=}


\section{Example from the FIR HTML definition}

\psfig{file=fir-seqStatement.ps,height=7in,silent=}


\chapter{The SAVANT Implementation of AIRE}

\section{Goals for the SAVANT Implementation of AIRE}

\begin{itemize}
\item Strictly adhere to the standard
\item Attempt to enforce the intended usage
    \begin{itemize}
    \item making non-final classes abstract to prevent their
        instantiation 
    \item using strong typing to enforce interfaces
    \end{itemize}
\item Encapsulate all core AIRE functionality
\item Support user extensibility
\end{itemize}


\section{Organization of the SAVANT Distribution}

\begin{small}
\begin{alltt}
~/savant> ls
COMPONENTS              CVS/                    INSTALL
INSTALL-FOR-SIMULATION  LGPL                    LICENSE
README                  RELEASENOTES            bin/
doc/                    lib/                    src/
~/savant> 
\end{alltt}
\end{small}


\section{savant/doc}

\begin{small}
\begin{alltt}
~>ls savant/doc/
README             libraryManager/    programmers/   simulationManual/

~>
\end{alltt}
\end{small}

\begin{itemize}
\item overview.texi: overview of the {\tt IIRScram} classes
\item programmers.texi: programmer's guide
\end{itemize}


\section{savant/src}

\begin{small}
\begin{alltt}
~>ls savant/src/
total 945
 920 Makefile         1 TODO             2 savant.hh        2 version.hh
   6 Makefile.bak     1 aire/            1 scram/
   6 Makefile.in      5 main.cc          1 util/
~>
\end{alltt}
\end{small}

\begin{itemize}
\item location of main makefile
\item {\tt main.cc}: driver code for scram
\item {\tt version.hh}: specifies version/release date of distribution
\end{itemize}



\section{savant/src/aire}

\begin{small}
\begin{alltt}
~>ls savant/src/aire/
total 55
   9 IIR/                     7 IIRKind.hh
  18 IIRBase/                18 IIRScram/
   2 IIRBasicDataTypes.hh    
~>
\end{alltt}
\end{small}

\begin{itemize}
\item IIR/FIR common headers located here
\item IIRBase: location of public AIRE/IIR methods
\item IIRScram: location of scram specific data/methods
\item IIR: leaf nodes for instantiation and derivation
\end{itemize}


\section{IIRBase Contains}

\begin{itemize}
\item Public interface described in the AIRE spec 
\item Protected/Private data/methods to support public interface
\end{itemize}


\section{IIRScram Contains}

\begin{itemize}
\item Methods for general use
    \begin{itemize}
    \item {\tt transmute()} 
    \item {\tt publish\_vhdl()}
    \item {\tt publish\_cc()}
    \end{itemize}
\item Methods not for general use
    \begin{itemize}
    \item type checking routines for SCRAM
    \item symbol table management functions for SCRAM
    \end{itemize}
\end{itemize}


\section{IIR Contains}

\begin{itemize}
\item empty constructor/destructors
\item no other private/protected/public functions or data
\end{itemize}


\section{savant/src/scram}

\begin{small}
\begin{alltt}
~>ls savant/src/scram/
total 259
   6 FlexLexer.h              9 scram.cc
   2 README                   2 scram.hh
   2 RIGHTS                   2 scram.man
  22 VHDLLexer.flex           3 scram_func.hh
   3 VHDLLexer.hh             6 symbol_lookup.cc
   3 VHDLToken.hh             5 symbol_lookup.hh
   2 Xdefaults               10 symbol_table.cc
   2 bool.hh                  6 symbol_table.hh
   2 config.hh              160 vhdl.gg
   3 declaration_chain.hh     9 vhdl.hh
~>
\end{alltt}
\end{small}


\section{savant/src/util}

\begin{small}
\begin{alltt}
~>ls savant/src/util/
total 71
   4 arg_parser.cc          4 error_func.cc          8 set.hh
   5 arg_parser.hh          4 error_func.hh          3 switch_file.cc
   2 container.hh           4 hash_table.hh          3 switch_file.hh
   7 dl_list.hh            20 resolution_func.cc
   2 elaborate_info.hh      5 resolution_func.hh
~>
\end{alltt}
\end{small}

\begin{itemize}
\item {\tt arg\_parser.\{hh,cc\}} parses command line arguments
    (discussed more fully tomorrow)
\end{itemize}


\section{Programming Practices in SAVANT Development}

\begin{itemize}
\item All SAVANT/AIRE class names directly correspond to the AIRE spec
\item All AIRE specific data/methods reside in {\tt IIRBase\_}
\item All SCRAM specific data/methods reside in {\tt IIRScram\_}
\item Names of all extension methods have a leading underscore
\item All {\tt IIR\_} classes are empty
\item All C++ headers separate from bodies
\item Fully descriptive names used whenever possible
\end{itemize}


\chapter{Extensibility in SAVANT}

%%\section{``Macro'' Derivation of AIRE}

%%\psfig{file=extensible-if.ps,angle=270,height=5in,silent=}


%%\section{``Micro'' Derivation of AIRE}

%%\centerline{\psfig{file=savant-if.ps,angle=270,height=5in,silent=}}


\section{``Actual'' Derivation of AIRE}

\bigskip
\bigskip
\bigskip

\psfig{file=actual-if.ps,angle=270,width=6.5in,silent=}


\section{Compare with the AIRE Spec}

\psfig{file=iir-extensible.ps,height=7in,silent=}



\section{All AIRE Classes Occur as 3 SAVANT Class Definitions}

\bigskip
\bigskip
\psfig{file=node-implementation.ps,height=4in,silent=}


\section{Class Derivations Limited To....}

\begin{itemize}
\item Abstract and concrete classes in {\tt IIR}
\end{itemize}


\section{Why this Structure?}

\begin{itemize}
\item SCRAM instantiates objects
\item Instantiation causes invocation of parent constructors
\item Virtual function tables are completed
\item Enables extensibility w/o forcing modifications to code in the parser
\end{itemize}



\section{Huh?}

\begin{itemize}
\item SCRAM instantiates concrete classes in {\tt IIR}
\item The IIR tree is built by the SCRAM parser
\item User defined extensions must then be inserted below the concrete,
    instantiatable nodes.
\end{itemize}


\section{Extending {\tt IIR\_Declaration}}

\noindent
\begin{minipage}{2.25in}
Classes can be added to the ``micro'' hierarchy to extend the
functionality of the system without modifying the parser.
\end{minipage} \hfill \begin{minipage}{3in}
\psfig{file=extended-declaration.ps,height=5in,silent=}
\end{minipage}


\section{Code Changes for Extension}

\begin{itemize}
\item build directory containing extension classes
\item modify the makefile accordingly (tomorrow's lecture)
\item change the derivation tree for the relevant classes in {\tt IIR}
    \begin{itemize}
    \item all the classes that are to be extended
    \end{itemize}
\end{itemize}

\chapter{Review of SAVANT IIR Classes}

\section{Example Studied}

\noindent
In the remainder of this time period, we will trace the complete
derivation tree from the root {\tt class IIRBase} to {\tt class
IIR\_SignalDeclaration}. 


\section{From IIRBase to IIR\_SignalDedclaration: \\
  Exploring the SAVANT Class Hierarchy} 

\subsection{IIRBase.hh}

\begin{alltt}
\begin{small}
#ifndef IIRBASE\_HH  // All header files are wrapped in this manner.
#define IIRBASE\_HH  // Only shown here...

// standard copyright notice, warranty disclaimer, author identification, and

//---------------------------------------------------------------------------
// 
// $Id: programmers.tex,v 1.6 1999/03/19 20:53:36 ramanan Exp $
// 
//---------------------------------------------------------------------------

#include "IIRBasicDataTypes.hh"

class IIRBase \{

public:

  virtual IIR\_Kind get\_kind() = 0;
  virtual IIR\_Char *get\_kind\_text() = 0;

  void set\_file\_name(IIR\_Identifier *file\_name) \{ . . . \}
  void set\_sheet\_name(IIR\_Identifier *sheet\_name) \{ . . . \}
  void set\_line\_number(IIR\_Int32 line\_number);
  void set\_column\_offset(IIR\_Int32 column\_offset);
  void set\_character\_offset(IIR\_Int32 character\_offset);
  void set\_x\_coordinate(IIR\_Int32 x\_coordinate);
  void set\_y\_coordinate(IIR\_Int32 y\_coordinate);

  IIR\_Identifier *get\_file\_name()  \{return iir\_file\_name;\}
  IIR\_Identifier *get\_sheet\_name() \{return iir\_sheet\_name;\}

  IIR\_Int32 get\_line\_number()      \{return iir\_line\_number;\}
  IIR\_Int32 get\_column\_offset()    \{return iir\_column\_offset;\}
  IIR\_Int32 get\_character\_offset() \{return iir\_character\_offset;\}
  IIR\_Int32 get\_x\_coordinate()     \{return iir\_x\_coordinate;\}
  IIR\_Int32 get\_y\_coordinate()     \{return iir\_y\_coordinate;\}

protected:
  
  IIRBase();
  virtual ~IIRBase() = 0;
    
private:
  
  IIR\_Identifier *iir\_file\_name;
  IIR\_Identifier *iir\_sheet\_name;

  IIR\_Int32  iir\_line\_number;
  IIR\_Int32  iir\_column\_offset;
  IIR\_Int32  iir\_character\_offset;
  IIR\_Int32  iir\_x\_coordinate;
  IIR\_Int32  iir\_y\_coordinate;
\};
\end{small}
\end{alltt}


\subsection{IIRScram.hh}

\begin{alltt}
\begin{small}
#ifndef DEVELOPER\_ASSERTIONS
#include <assert.h>
#endif

extern switch\_file \_vhdl\_out;  //file for vhdl output
extern switch\_file \_cc\_out;    //file for c++ output

class IIRScram : public IIRBase \{

public:

  virtual void \_publish\_vhdl();
  virtual void \_publish\_cc();
  virtual IIR\_Boolean \_is\_declaration();
  virtual IIR\_Boolean \_is\_ascending\_range();
  virtual IIR\_Boolean \_is\_name();
  virtual IIR\_Boolean \_is\_signal();
  virtual IIR\_Boolean \_is\_variable();
  virtual IIR\_Boolean \_is\_text\_literal();
  virtual IIR\_Boolean \_is\_discrete\_type();

  virtual IIR  *\_transmute();

  //The following function is used for code generation that does runtime 
  //elaboration
  virtual void \_publish\_cc\_elaborate();

  void \_report\_undefined\_scram\_fn(char *);

  // These methods have to do with semantic checks and such.
  virtual set<IIR\_Declaration> *\_symbol\_lookup();
  virtual set<IIR\_Declaration> *\_symbol\_lookup( IIR\_Declaration *);

  virtual set<IIR\_TypeDefinition> *\_get\_lval\_set();
  virtual set<IIR\_TypeDefinition> *\_get\_rval\_set();
  
  virtual void \_type\_check( set<IIR\_TypeDefinition> * );
  virtual void \_type\_check( IIR\_TypeDefinition * );

  virtual ostream &\_print( ostream & );

  static void \_set\_symbol\_table( symbol\_table *s\_t );
  static symbol\_table *\_get\_symbol\_table( );

protected:

  IIRScram();
  virtual ~IIRScram() = 0;
  static symbol\_table *sym\_tab;
    
private:

\};

inline ostream &
operator<<(ostream &os, IIRScram &is )\{
  return is.\_print( os );
\}
\end{small}
\end{alltt}


\subsection{IIR.hh}

\begin{alltt}
\begin{small}
class IIR : public IIRScram \{

public:

  virtual ~IIR() = 0;

protected:

  IIR();
    
private:
\};
\end{small}
\end{alltt}

\noindent
\textbf{Note:} this is an abstract class


\subsection{IIRBase\_Declaration.hh}

\begin{alltt}
\begin{small}
class IIRBase\_Declaration : public IIR \{

public:

  IIR\_Kind get\_kind() \{
    return IIR\_DECLARATION;
  \}

  IIR\_Char *get\_kind\_text() \{
    return "IIR\_Declaration";
  \}

  void set\_declarator( IIR\_TextLiteral *declarator );
  IIR\_TextLiteral *get\_declarator();

protected:
  
  IIRBase\_Declaration();
  virtual ~IIRBase\_Declaration() = 0;
    
private:
  
  IIR\_TextLiteral *declarator;
\};
\end{small}
\end{alltt}


\subsection{IIRScram\_Declaration.hh}

\begin{alltt}
\begin{small}
class IIRScram\_Declaration : public IIRBase\_Declaration \{

public:

  virtual void \_publish\_vhdl();

  // Methods for C++ code generation

  virtual IIR\_Boolean \_is\_type() \{ return FALSE; \}
  virtual IIR\_Boolean \_is\_access\_type() \{ return FALSE; \}
  virtual IIR\_Boolean \_is\_read\_file() \{ return FALSE; \}
  virtual IIR\_Boolean \_is\_write\_file() \{ return FALSE; \}
  virtual IIR\_Boolean \_is\_object\_decl() \{ return FALSE; \}
  virtual IIR\_Boolean \_is\_signal() \{ return FALSE; \}
  virtual IIR\_PortList *\_get\_port\_map()\{ return NULL; \}
  virtual IIR\_GenericList *\_get\_generic\_map()\{ return NULL; \}

  virtual IIR\_Declaration *\_find\_symbol( IIR\_Name *look\_for )\{
    \_report\_undefined\_scram\_fn("\_find\_symbol( IIR\_Name *)");
    return NULL;
  \}

  virtual char * \_get\_type\_string()\{
    return "(unknown)";
  \}
  enum declaration\_type \{ ERROR = 0, UNDEFINED, VARIABLE, SHARED\_VARIABLE,
                          TYPE, SUBTYPE, SIGNAL, PROCEDURE, INTERFACE,
                          FUNCTION, S\_FILE, ENTITY, CONSTANT, CONFIGURATION,
                          COMPONENT, ATTRIBUTE, ALIAS, ARCHITECTURE, PACKAGE,
                          PACKAGE\_BODY, INTERFACE\_VARIABLE, 
                          INTERFACE\_SIGNAL, INTERFACE\_CONSTANT,
                          INTERFACE\_FILE, LABEL, LITERAL, UNITS, GROUP,
                          LIBRARY, LAST\_DECLARATION\_TYPE \};

  virtual declaration\_type \_get\_type();

  void \_set\_scope( IIR\_Int32 );
  IIR\_Int32 \_get\_scope();
  virtual IIR\_TypeDefinition *\_get\_lval();
  virtual IIR\_TypeDefinition *\_get\_rval();

  virtual bool \_check\_param( IIR\_TypeDefinition *decl, int arg\_num );
  virtual bool \_is\_implicit\_declaration();

  IIR\_Attribute *\_get\_attribute\_name();
  void \_set\_attribute\_name( IIR\_Attribute * );

  IIR\_DeclarationList implicit\_declarations;
  IIR\_Declaration *\_find\_in\_implicit\_list( char * );

  virtual IIR\_TypeDefinition *\_get\_type\_of\_element( int );
  virtual IIR\_Int32 \_get\_num\_indexes();

  virtual ostream & \_print( ostream & );

protected:

  IIRScram\_Declaration();
  virtual ~IIRScram\_Declaration() = 0;
    
private:

  IIR\_Int32 scope;
  IIR\_Attribute *attribute\_name;
\};
\end{small}
\end{alltt}


\subsection{IIRScram\_Declaration.hh}

\begin{alltt}
\begin{small}
class IIR\_Declaration : public IIRScram\_Declaration \{

public:

protected:
  
  IIR\_Declaration() \{\};
  virtual ~IIR\_Declaration() = 0;
  
private:
  
\};
\end{small}
\end{alltt}


\subsection{IIRBase\_ObjectDeclaration.hh}

\begin{alltt}
\begin{small}
class IIRBase\_ObjectDeclaration : public IIR\_Declaration \{

public:

  IIR\_Kind get\_kind() \{ return IIR\_OBJECT\_DECLARATION; \}
  IIR\_Char *get\_kind\_text() \{ return "IIR\_ObjectDeclaration"; \}

  void set\_subtype(IIR\_TypeDefinition* subtype);
  IIR\_TypeDefinition* get\_subtype();

  IIR\_AttributeSpecificationList attributes;

protected:

  IIRBase\_ObjectDeclaration();
  virtual ~IIRBase\_ObjectDeclaration() = 0;
    
private:
  IIR\_TypeDefinition* subtype;
\};
\end{small}
\end{alltt}


\subsection{IIRScram\_ObjectDeclaration.hh}

\begin{alltt}
\begin{small}
class IIRScram\_ObjectDeclaration : public IIRBase\_ObjectDeclaration \{

public:

  IIR\_TypeDefinition *\_get\_lval();
  IIR\_TypeDefinition *\_get\_rval();
  set<IIR\_TypeDefinition> *\_get\_rval\_set();

  IIR\_Boolean \_is\_object\_decl();

  IIR\_Int32 \_get\_num\_indexes();
  IIR\_TypeDefinition *\_get\_type\_of\_element( int index );

protected:

  IIRScram\_ObjectDeclaration() \{\}
  virtual ~IIRScram\_ObjectDeclaration() = 0;
    
private:
\};
\end{small}
\end{alltt}


\subsection{IIR\_ObjectDeclaration.hh}

\begin{alltt}
\begin{small}
class IIR\_ObjectDeclaration : public IIRScram\_ObjectDeclaration \{

public:

protected:

  IIR\_ObjectDeclaration() \{\};
  virtual ~IIR\_ObjectDeclaration() = 0;
  
private:
  
\};
\end{small}
\end{alltt}


\subsection{IIRBase\_SignalDeclaration.hh}

\begin{alltt}
\begin{small}
class IIRBase\_SignalDeclaration : public IIR\_ObjectDeclaration \{

public:

  IIR\_Kind get\_kind() \{return IIR\_SIGNAL\_DECLARATION;\}
  IIR\_Char *get\_kind\_text() \{return "IIR\_SignalDeclaration";\}

  void set\_value(IIR* value);
  IIR* get\_value();
  void set\_signal\_kind(IIR\_SignalKind signal\_kind);
  IIR\_SignalKind get\_signal\_kind();

protected:
  
  IIRBase\_SignalDeclaration();
  virtual ~IIRBase\_SignalDeclaration() = 0;
    
private:
  
  IIR* value;
  IIR\_SignalKind signal\_kind;

\};
\end{small}
\end{alltt}


\subsection{IIRScram\_SignalDeclaration.hh}

\begin{alltt}
\begin{small}
class IIRScram\_SignalDeclaration : public IIRBase\_SignalDeclaration \{

public:

  void \_publish\_cc();
  IIR\_Boolean \_is\_signal()\{ return TRUE; \}

  declaration\_type \_get\_type();

protected:

  IIRScram\_SignalDeclaration() \{\}
  virtual ~IIRScram\_SignalDeclaration() = 0;
\};
\end{small}
\end{alltt}


\subsection{IIR\_SignalDeclaration.hh}

\begin{alltt}
\begin{small}
class IIR\_SignalDeclaration : public IIRScram\_SignalDeclaration \{

public:

  IIR\_SignalDeclaration() \{\};
  virtual ~IIR\_SignalDeclaration();
  
protected:
  
private:
  
\};
\end{small}
\end{alltt}

\chapter{Programming Exercise 1}

\section{Problem Statement}

\begin{enumerate}
\item Build a mechanism to profile the static structure of a VHDL model
\item Modify the of SAVANT classes in {\tt IIRScram\_}
    \begin{enumerate}
    \item Add the static variable {\tt count} of type to the class
    \item Modify the constructor to increment {\tt count}
    \item Modify the destructor to decrement {\tt count}
    \end{enumerate}
\item Begin with {\tt IIRScram\_SignalDeclaration.hh}
\item Recompile scram
\item Run with supplied test file
\item Print the result
\item Compare the results to the original test file.  Is the count correct?
\item Continue with additional VHDL constructs of your choice.
\end{enumerate}


\section{Detailed Programming Changes}

\subsection{Edit the file {\tt IIRScram\_SignalDeclaration.hh}}

  \begin{enumerate}
  \item In the {\tt private:} section, add: \\
    {\tt static IIR\_Int32 count;}
  \item In the {\tt public:} section, add: \\
    {\tt static IIR\_Int32 get\_count()\{ return count; \};}
  \item In the {\tt protected:} section, change the line: \\
    {\tt IIRScram\_SignalDeclaration()\{\}} \\
    to \\
    {\tt IIRScram\_SignalDeclaration()\{count++;\}}
  \item Save the file.
  \end{enumerate}

\subsection{Edit the file {\tt IIRScram\_SignalDeclaration.cc}}

  \begin{enumerate}
  \item Add the following line somewhere in the file: \\
    {\tt IIR\_Int32 IIRScram\_SignalDeclaration::count;}
  \item Change the line: \\
    {\small {\tt IIRScram\_SignalDeclaration::}\verb+~+{\tt IIRScram\_SignalDeclaration()\{\}}} \\
    to \\
    {\small {\tt IIRScram\_SignalDeclaration::}\verb+~+{\tt IIRScram\_SignalDeclaration()\{count--;\}}}
  \end{enumerate}
  

\section{Recompile}

\begin{enumerate}
\item move to the {\tt savant/src/} directory
\item type: {\tt make aire/IIRScram/IIRScram\_SignalDeclaration.o}
\item Re-edit  {\tt IIRScram\_SignalDeclaration.hh} and/or \\
    {\tt IIRScram\_SignalDeclaration.cc} until it compiles error free
    (ask an instructor for help if necessary).
\end{enumerate}


\section{Reporting the Results of the Static Counting}

\begin{enumerate}
\item Edit the file {\tt main.cc}
\item Just before the last \}, add the lines: \\
    {\small {\tt \#include "IIR\_SignalDeclaration.hh"}} \\
    {\small {\tt cout << "Signal count: " << IIR\_SignalDeclaration::get\_count() << endl;}}
\item Recompile
    \begin{enumerate}
    \item cd to the {\tt savant/src/} directory
    \item type {\tt make}
    \item If problems arise, contact an instructor for help.
    \end{enumerate}
\end{enumerate}


\section{Interesting results}

\begin{enumerate}


\item
Now that we have a modified {\tt scram} binary, we can test it on some
vhdl files.  After running the new {\tt scram} on some simple files,
count the number of signal declarations in the VHDL versus the number you
program reports.

\item
If the number the program reports is greater than the number you count,
then count the number of signal valued attributes, and add that number to
the number reported.  As required by AIRE, {\tt scram} internally
creates declarations for various attributes to augment code generation in
the back end. 

\end{enumerate}

\chapter{Advanced Savant Programming}

\section{Recall the ``Micro'' Derivation of AIRE}

\psfig{file=savant-if.ps,angle=270,width=6.5in,silent=}


\section{Recall the ``Actual'' Derivation of AIRE}

\bigskip
\bigskip
\bigskip

\psfig{file=actual-if.ps,angle=270,width=6.5in,silent=}


\section{User Modifications}

\begin{itemize}
\item Define a new class that shadows an existing method
\item Add a new virtual function to the IIR root class ({\tt IIR}) with
    a default action that is selectively shadow'ed on a class by class
    basis 

\bigskip
\item \textbf{Note:} code changes near the root of the IIR tree can
    trigger numerous dependency relations and create a situation where
    seemingly small changes cause recompilation of virtually the entire
    source tree.
\end{itemize}


\section{Inserting a User Defined Class into the Hierarchy (Part I)}

\begin{minipage}{2in}
  As previously discussed, the default hierarchy of the SAVANT/AIRE
nodes looks like:
\end{minipage} \hfill \begin{minipage}{3in}
\psfig{file=node-implementation.ps,silent=}
\end{minipage}


\section{Inserting a User Defined Class into the Hierarchy (Part II)}

\begin{minipage}{2.5in}
When inserting a user defined class into the hierarchy, the default
derivation is ``broken'' to look like:
\end{minipage} \hfill \begin{minipage}{3in}
\psfig{file=broken-derivation.ps,width=3in,silent=}
\end{minipage}


\section{Inserting a User Defined Class into the Hierarchy (Part III)}

\noindent
Essentially, the user-defined class must be derived from the IIR level
just ``underneath'' the IIR level, in this case, IIRScram.  In
addition, the derivation of the IIR level must be modified such that
it inherits directly from the user defined class.


\section{Preparations outside the AIRE Classes}

\begin{itemize}
\item Updating the Makefile
\item Modifying {\tt main()} to invoke new methods
\item Defining and Parsing new command line arguments
\end{itemize}


\section{Editing {\tt Makefile.in} for Inclusion of New Classes}

\noindent
When new classes are added to the SAVANT/AIRE hierarchy, the new classes
must be compiled and included into the libraries.  The file
{\tt Makefile.in} that comes with the distribution has a simple
mechanism for adding classes to {\tt libaire.a}.  To include the
classes in the subdirectory {\tt IIRSavantGeeks} into
{\tt libaire.a}, find the following lines in
{\tt Makefile.in}:

\noindent
\begin{small}
\begin{alltt}
# If you are extending the AIRE classes with your own, put your subdirectory
# in this list and it will automatically get compiled into libaire.
AIRE_SUBDIRS = $(AIRE) $(AIRE)/IIRBase $(AIRE)/IIRScram $(AIRE)/IIR
\end{alltt}
\end{small}


\section{Editing {\tt Makefile.in} (Part II)}

\noindent
Adding a subdirectory to this list has the following consequences:
\begin{itemize}
\item
All ``.cc'' files are compiled into ``.o'' files.
\item
All of the ``.o'' files generated get written into {\tt libaire.a}.
\item
The named directory is added to the list searched for C++ header files.
\item
{\tt make clean} will remove the ``.o'' files in this directory.
\end{itemize}

\noindent
\textbf{Note:} after editing {\tt Makefile.in}, {\tt configure} or
{\tt config.status} needs to be re-run (to generate {\tt Makefile}),
and dependencies need to be rebuilt with {\tt make depend}.


\section{Modifying ``main''}

\noindent
The procedure {\tt main} in {\tt savant/src/main.cc}
instantiates SAVANT's parser class, {\tt scram}.  {\tt scram}
essentially has one public method, {\tt parse\_files}.  This method
takes the following arguments:

\begin{description}
\item[int argc] This variable tells the parser how many filenames are
listed in the next argument.
\item[char **argv] This is an array of strings, holding the filenames
to parse.
\item[symbol\_table *] This is the symbol table you want to use for parsing.
\end{description}

\noindent
The method {\tt parse\_files} returns a {\tt dl\_list<IIR\_DesignFile>
*}.  Once this list is generated, the rest of the code in main my do
whatever it likes with it.  This is where methods in extension classes
are normally invoked.


\section{Adding Command Line Arguments to Scram} 

\begin{itemize}

\item
When extending the SAVANT system with new capabilities, it will often
be desirable to add command line options to scram to control them.

\item
In the {\tt savant/src/util} subdirectory there is a class that
implements an argument parser (in files {\tt arg\_parser.hh} and
{\tt arg\_parser.cc}).  This class is used by scram to process 
the command line, and can easily be extended to support additional
options.

\end{itemize}


\section{Argument Parser Initialization}

In the file {\tt savant/src/main.cc}, the following lines
initialize the array of {\tt arg\_record}s passed to the arg\_parser:

\begin{footnotesize}
\begin{alltt}
static arg\_parser::arg\_record arg\_list[] = \{
  \{"-publish-vhdl","publish VHDL", &publish\_vhdl, arg\_parser::ARG\_BOOLEAN\},
  \{"-publish-cc","publish c++", &publish\_cc, arg\_parser::ARG\_BOOLEAN\},
  \{"-no-file-output", "send publish\_cc output to stdout instead of compilable files",  
    &no\_file\_output, arg\_parser::ARG\_BOOLEAN\},
  \{"-warranty-info", "print information about (lack of) warranty",
    &print\_warranty, arg\_parser::ARG\_BOOLEAN \},
  \{NULL, NULL\}
\};
\end{alltt}
\end{footnotesize}


\section{Syntax of arg\_records (Part I)}

\noindent
Each arg\_record consists of the following fields:

\begin{description}
\item[char *arg\_text] This is the text of the argument itself, like
{\tt --help}.
\item[char *arg\_help] This is the description of the argument's
function that is printed with usage messages.
\item[void *storage] This is a pointer to whatever type of storage
this type of argument needs (as determined by the next parameter).
\item[arg\_type type] This enumeration what type of argument this is -
a boolean flag, or a string, for instance.  See inline documentation
for current options.
\end{description}


\section{Syntax of arg\_records (Part I)}

\noindent
To add a new argument to {\tt scram}:

\begin{description}
\item[Modify arg\_list] Described above.
\item[Declare new variable] That the argument will effect.  Don't
forget to initialize the variable as well.
\end{description}


\chapter{Programming Exercise 2}

\section{Problem Statement}

\begin{description}
\item \
\begin{enumerate}
\item Build a mechanism to obfuscate identifiers in VHDL models
\item Make a {\tt IIRTraining} directory in {\tt savant/src/aire/iir}
\item Build the class: \\
    {\tt IIRTraining\_Identifier} derived from: \\
    {\tt IIRScram\_Identifier} that shadows the method: \\
    {\tt void \_publish\_vhdl()} in {\tt IIRScram\_Identifier} 
\item Obscure the printed identifier output by {\tt \_publish\_vhdl()}
\item In the directory savant/src/aire/iir/IIR:
    \begin{enumerate}
        \item Modify the file {\tt IIR\_Identifier.hh} to include
            {\tt IIRTraining\_Identifier.hh} instead of
            {\tt IIRScram\_Identifier.hh} 
        \item Derive the class {\tt IIR\_Identifer} from
            {\tt IIRTraining\_Identifier} instead of \\
            {\tt IIRScram\_Identifier} 
    \end{enumerate}
\item Recompile scram
\item Run against a VHDL file that contains an object of some type from
    package standard
\item What prints in the data type declarator?
\item How can this be fixed?
\item Continue with additional obfuscations of your choice.
\end{enumerate}
\end{description}




\section{Detailed Programming changes}

\begin{enumerate}
\item
  Make a new directory for extension classes:\\
  \\*
  {\tt savant/src/aire/iir/IIRTraining}
\item
  Create new class: \\
  \\*g
  {\tt IIRTraining\_Identifier}.
\end{enumerate}

\section{{\tt IIRTraining\_Identifier.hh}}

\begin{small}
\begin{alltt}
#ifndef IIRTRAINING\_IDENTIFIER\_HH
#define IIRTRAINING\_IDENTIFIER\_HH

#include ``IIRScram\_Identifier.hh''

class IIRTraining\_Identifier : public IIRScram\_Identifier \{

public:
  \_publish\_vhdl();  // This is defined as virtual in base classes.  
                      // This definition overrides.

protected:
  IIRTraining\_Identifier() \{\};
  ~IIRTraining\_Identifier() = 0;
\}
#endif
\end{alltt}
\end{small}


\section{{\tt IIRTraining\_Identifier.cc}}

\begin{small}
\begin{alltt}
#include "IIRTraining\_Identifier.hh"
#include "switch\_file.hh"
#include <ctype.h>

IIRTraining\_Identifier::~IIRTraining\_Identifier() \{\}

void 
IIRTraining\_Identifier::\_publish\_vhdl()\{
  int i;
  for( i = 0; i < length; i++ )\{
    if( isalpha((text[i] + 1)) )\{
      \_vhdl\_out << (char)(text[i] + 1);
    \}
    else\{
      \_vhdl\_out << (char)text[i];
    \}
  \}
\}
\end{alltt}
\end{small}



\section{Modify {\tt IIR\_Identifier.hh} in savant/src/aire/iir/IIR}

\begin{small}
\begin{alltt}
#ifndef IIR\_IDENTIFIER\_HH
#define IIR\_IDENTIFIER\_HH

#include "IIRTraining\_Identifier.hh"

class IIR\_Identifier : public IIRTraining\_Identifier \{

public:
  
  IIR\_Identifier() \{\};
  ~IIR\_Identifier() \{\};
  
protected:  private:
  
\};

#endif
\end{alltt}
\end{small}


\section{Add {\tt IIRTraining} to Makefile}

\begin{enumerate}

\item
Modify {\tt Makefile.in} to include the files from
{\tt IIRTraining} into {\tt libaire.a}.  Look for the following
lines in {\tt Makefile.in}:

\begin{footnotesize}
\begin{alltt}
# If you are extending the AIRE classes with your own, put your subdirectory
# in this list and it will automatically get compiled into libaire.
AIRE_SUBDIRS = $(AIRE) $(IIR)/IIRBase $(IIR)/IIRScram $(IIR)/IIR
\end{alltt}
\end{footnotesize}

\item
Change it to read:

\begin{footnotesize}
\begin{alltt}
# If you are extending the AIRE classes with your own, put your subdirectory
# in this list and it will automatically get compiled into libaire.
AIRE_SUBDIRS = $(AIRE) $(IIR)/IIRBase $(IIR)/IIRScram $(IIR)/IIR $(IIR)/IIRTraining 
\end{alltt}
\end{footnotesize} 

\end{enumerate}

%%$ to fix emacs fontlock coloring

\section{Build new {\tt Makefile} and Compile} 

\begin{enumerate}

\item
Build a new Makefile from Makefile.in by re-running the script\\
{\tt savant/configure/configure}.

\item
Build dependencies in the new {\tt Makefile} using the command
{\tt make depend}.

\item
Build {\tt scram} by issuing the command {\tt make}.

\end{enumerate}

\begin{small}
\noindent
\textbf{NOTE:} You can make sure that your new class compiles before
rebuilding the entire system by:

\indent
{\tt make aire/iir/IIRTraining/IIRTraining\_Identifier.o}

\noindent
Additionally, you can build {\tt libaire.a} to see if you modified the
{\tt Makefile} correctly:

\indent
{\tt make ../lib/libaire.a}

\end{small}

\chapter*{Acknowledgments}

This research has been conducted with the participation of many
investigators.  While not an complete list, the following individuals
have made notable direct and/or indirect contributions to this effort
(in alphabetical order):
Jeff Carter,
Harold Carter,
Praveen Chawla,
John Hines,
Herb Hirsch,
Timothy J. McBrayer,
Greg Peterson,
Al Scarpelli,
Mike Shellhause and
John Willis.
We wish to express our sincerest gratitude for the time that you spent
reviewing and commenting on our designs.

This research was supported in part by MTL Systems, Inc and the Wright
Laboratory at Wright-Patterson AFB.  Thank you for your support.

\end{document}