trick/trick_source/codegen/Interface_Code_Gen/design.dox_in

/**

@page LEVEL2 Interface Code Generator Design

The Interface Code Generator (ICG) creates class/struct layout information, called
attributes, used to convert string variable names to simulation memory
addresses.  The attributes are used with several of Trick's services
including checkpointing, data recording, and the variable server.

ICG execution is divided into 2 parts.

-# Executing the Clang C++ frontend to parse all header files and extract
   class/struct information.
-# Print class/struct information as attributes in input/output source code.

@section LEVEL3 Clang C++ Frontend

ICG uses the Clang frontend.  Clang is a C/C++ frontend to the LLVM compiler.
Clang and LLVM provide libraries that allow developers to create their own tools
using the compiler.  ICG calls the clang parser to process the header
files and converts the source text into a tree form called an abstract syntax tree
(AST).  Clang completely handles all textual parsing.  ICG provides classes to
provide input parameters to the compiler and to extract the information out of the
AST.

@section LEVEL4 Parser Setup

The frontend has some parameters that must be set in order for the parser to
execute.

@section LEVEL5 Parsing Language

The S_source.hh file where parsing begins is written in C++.  The frontend is set to
parse C++.

@section LEVEL5 Target Architecture

The frontend requires a target architecture set.  ICG does not pass the AST to the
next stage of compiler tools after the frontend, so it doesn't matter what the
target architecture is set to.  Setting the target to the the default architecture
works.

@section LEVEL4 Preprocessor

The frontend includes a preprocessor.  The preprocessor handles include and define
statements.  ICG provides a pair of classes that interact with the clang preprocesor.
The HeaderSearchDirs class to provide the preprocessor with include search
directories and default defines.  The CommentSaver class saves all comments parsed
by the preprocessor.  These classes are used throughout the rest of ICG execution.

@section LEVEL5 HeaderSearchDirs

The HeaderSearchDirs manages the header search directories used by the preprocessor
and provides an interface for querying the inclusion status of a directory.  Since
this class is closely related to the preprocessor, it also handles define macros.

The HeaderSearchDirs class provides a list of include search directories to the
clang preprocessor.  There are two types of include directories, system include
directories and user provided directories.  Both types must be supplied to the
preprocessor.

The system include directories are retrieved by running the TRICK_CPPC compiler
in verbose preprocessor mode with no input code.  When the compiler is run
in this mode, it prints the system include directories built into the compiler.
This class parses that output for the system include directories and feeds the
list into the preprocessor.

The user include directories are retrieved from the command line when executing
ICG.  Typically ICG is called with the TRICK_CXXFLAGS environment variable
included as an argument.  TRICK_CXXFLAGS may include -I<include_dir> strings.
These include directories are parsed from the command line and fed to the
preprocessor.

This class parses the TRICK_ICG_EXCLUDE environment variable and manages a list
of directories ICG should not write any output source code.

The HeaderSearchDirs class provides boolean responses to questions to whether a
path is in a user directory or is in an TRICK_ICG_EXCLUDE directory.

@section LEVEL5 CommentSaver

The CommentSaver class saves comments found in user code and provides an iterface
for retrieving comments based on file name/line number.  The class also provides
an interface to retrieving several fields from a Trick header comment including
the ICG and ICG_EXCLUDE_TYPES fields.

The clang preprocessor includes a comment handler interface.  ICG uses
this interface to attach the CommentSaver class.  Each comment handled by this
class is stored in a map indexed by file name and line number.

@section LEVEL4 Abstract Syntax Tree (AST) Traversal

Traversing the resulting AST is bulk of ICG's work.  The clang compiler provides
an interface allowing ICG to attach handlers to process interesting events during
code parsing.  In this case, ICG only attaches a handler when clang is finished
parsing the entire input file, called HandleTranslationUnit.

When HandleTranslationUnit is start parsing the AST searching for top level
declarations we want to process.  From the top level recursively calls
tree parsers that specialize in extracting information about typedefs,
classes and structs, fields within each class/struct, and enumerations.

The following diagram shows the recursive class instantiation sequence as well
as the data returned to the caller.

@section LEVEL3 Writing Class/Struct Attributes

*/