More manual writing

dataflowAPI/doc/AST.tex

@@ -0,0 +1,151 @@
+\subsection{AST}
+\label{sec:ast}
+\definedin{common/h/DynAST.h}
+
+We provide a generic AST framework to represent tree structures. One example use
+case is to represent instruction semantics. This AST framework include the base
+class definitions for tree nodes and AST visitors. Users can inherit tree node
+classes to create their own AST structure and AST visitors to write their own
+analyses of the AST. 
+
+All AST node classes should be derived from class AST, which provides the
+following interfaces.
+
+\begin{center}
+\begin{tabular}{ll}
+\toprule
+AST::ID  & Meaning \\
+\midrule 
+    V\_AST & Base class type \\
+    V\_BottomAST & Bottom AST node \\
+    V\_ConstantAST & Constant AST node \\
+    V\_VariableAST & Variable AST node \\
+    V\_RoseAST & ROSEOperation AST node \\
+    V\_StackAST & Stack AST node \\
+    V\_InputVariableAST & InputVariable AST node \\
+    V\_ReferenceAST & Reference AST node \\
+    V\_StpAST & Stp AST node\\
+    V\_YicesAST & Yices AST node \\
+    V\_SemanticsAST & semantics AST node \\
+
+\bottomrule
+\end{tabular}
+\end{center}
+
+\begin{apient}
+typedef boost::shared_ptr<AST> Ptr;
+\end{apient}
+\apidesc{Every AST node class has this type for shared pointer access.}
+
+\begin{apient}
+typedef std::vector<AST::Ptr> Children;      
+\end{apient}
+\apidesc{The container type for the children of this AST.}
+
+\begin{apient}
+bool AST::operator==(const AST &rhs) const; 
+bool AST::equals(AST::Ptr rhs);
+\end{apient}
+\apidesc{Check whether two AST nodes are equal. Return \code{true} when two
+nodes are in the same type and are equal according to the \code{==} operator of that type.}
+
+\begin{apient}
+virtual unsigned AST::numChildren() const; 
+\end{apient}
+\apidesc{Return the number of children of this node.}
+
+\begin{apient}
+virtual AST::Ptr child(unsigned) const;
+\end{apient}
+\apidesc{Return the specified child.}
+
+\begin{apient}
+virtual const std::string format() const = 0;
+\end{apient}
+\apidesc{Return the string representation of the node.}
+
+\begin{apient}
+static AST::Ptr substitute(AST::Ptr in, AST::Ptr a, AST::Ptr b); 
+\end{apient}
+\apidesc{Substitute every occurrence of \code{a} with \code{b} in AST \code{in}.
+Return a new AST after the substitution.}
+
+\begin{apient} 
+virtual AST::ID AST::getID() const;
+\end{apient}
+\apidesc{Return the class type ID of this node.}
+
+\begin{apient}
+virtual Ptr accept(ASTVisitor *v);
+\end{apient}
+\apidesc{Apply visitor \code{v} to each node in this AST.}
+
+\begin{apient}
+AST::Ptr AST::ptr();
+\end{apient}
+\apidesc{Make a shared pointer of this object.}
+
+\begin{apient}
+virtual void AST::setChild(int i, AST::Ptr c);
+\end{apient}
+\apidesc{Set the \code{i}th child of this node to \code{c}.}
+
+
+Dataflow API provides two node types: internal nodes and leaf nodes, which can
+be defined:
+
+\begin{apient}
+#define DEF_AST_LEAF_TYPE(name, type)					
+#define DEF_AST_INTERNAL_TYPE(name, type)				
+\end{apient}
+\apidesc{These two macros define a leaf node class or an internal node class
+with a class name \code{name} and associate the class with a data type
+\code{type}. Note that the AST classes only represents the tree structure; the
+data type class \code{type} provides a way to embed other information into the
+AST. Both classes are derived from class \code{AST}.}
+
+After defining a leaf node class, the user can use the following interface to
+create leaf node objects:
+
+\begin{apient}
+typedef boost::shared_ptr<name> name::Ptr;			
+static name::Ptr name::create(type t);
+\end{apient}
+\apidesc{Create a leaf node object.}
+
+After defining an internal node class, the user can use the following interfaces to
+create internal node objects:
+
+\begin{apient}
+typedef boost::shared_ptr<name> name::Ptr;			
+static name::Ptr name::create(type t, AST::Ptr a);
+static name::Ptr name::create(type t, AST::Ptr a, AST::Ptr b);
+static name::Ptr name::create(type t, AST::Ptr a, AST::Ptr b, AST::Ptr c);
+static name::Ptr name::create(type t, AST::Children children);
+\end{apient}
+\apidesc{Create an internal node with data object \code{t} and the internal node
+has a single child \code{a}, or two children \code{a} and \code{b}, or three
+children \code{a}, \code{b}, and \code{c}, or a children vector \code{children}.}
+
+
+The ASTVisitor class defines the operations to take during visiting an AST for
+each AST node type. Users can inherit this class to write customized analyses
+for ASTs.
+
+\begin{apient}
+typedef boost::shared_ptr<AST> ASTVisitor::ASTPtr;
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(AST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(DataflowAPI::BottomAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(DataflowAPI::ConstantAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(DataflowAPI::VariableAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(DataflowAPI::RoseAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(StackAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(InputVariableAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(ReferenceAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(StpAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(YicesAST *);
+virtual ASTVisitor::ASTPtr ASTVisitor::visit(SemanticsAST *);
+\end{apient}
+\apidesc{Operations applied during visiting each type of AST node. The default
+behavior is returning the input parameter.}
+

dataflowAPI/doc/Abstractions.tex

@@ -7,24 +7,29 @@ \section{Abstractions}
 \begin{itemize}
 \item[Abstract Location] Represents a register or memory location (cite).
 DataflowAPI provides three types of abstract locations: registers, stack, and
-help. Register abstract locations are distinguished through register names.
-Stack abstract locations are distinguished by the offset within a stack frame
-and the function to which the stack frame belongs.
-Head abstract locations are distinguished by the virtual address of the
-location.
+help. A register abstract location represents a register and a register at two
+different program locations is represented with the same abstract location. 
+A stack abstract location consists of the stack frame to which it belongs and
+the offset within the stack frame. 
+A heap abstract location represents the virtual address of the heap variable. 
+
 \item[Abstract Region] Represents a set of abstract locations of the same type
 (cite). If an abstract region contains only a single abstract location, the
 abstract location is precisely represented. 
 If an abstract region contains more than one abstract locations, the region
-contains the type of the locations. For a memory region, it also contains 
-the memory address calculation that gives rise to this region. The address
-calculation is represented with an AST described below.
-\item[AST] Represents the symbolic expansion of an instruction's full semantics
-\item[Semantics Policy] Provides callbacks for each low-level operation an instruction may perform.
+contains the type of the locations. In the cases where it represents memory
+(either heap or stack), an abstract region also contains 
+the memory address calculation that gives rise to this region. 
+The address calculation is represented with an AST described below.
+
+\item[AST] Represents a symbolic expression of an instruction's full semantics.
+Specifically, an AST specifies the value of a register or a memory location is changed by this
+instruction.
+
 \item[Assignment] Represents a single data dependency of abstract regions in an instruction. For example, xchg eax, ebx creates two assignments: one from pre-instruction eax to post-instruction ebx, and one from pre-instruction ebx to post-instruction eax.
+
 \item[Stack Height] Represents the difference between a value in an abstract location and the stack pointer at a function's call site.
 \item[Graph] Represents a directed graph.
-\item[Symbolic Evaluator] Translates a graph representing a program slice (cite) into a mapping from assignments to ASTs.
 \end{itemize}
 
 

dataflowAPI/doc/Examples.tex

@@ -0,0 +1,10 @@
+\section{Examples}
+\label{sec:examples}
+
+\subsection{Slicing}
+
+\subsection{Symbolic Evaluation}
+
+\subsection{Liveness Analysis}
+
+\subsection{Stack Analysis}

dataflowAPI/doc/Intro.tex

@@ -3,11 +3,24 @@ \section{Introduction}
 
 DataFlowAPI aggregates a collection of dataflow analysis algorithms that are
 useful in Dyninst development into a single library. These algorithms can also
-be a foundation for users to build customized analysis. Currently, these algorithms include:
+be foundations for users to build customized analyses. Currently, these algorithms include:
+
 \begin{itemize}
-\item Slicing
-\item Stack Analysis
-\item Instruction Semantics
-\item Symbolic Expansion and Evaluation
-\item Register Liveness
+\item [Slicing] Takes a program location as input and can either slice
+backward to determine which instructions affect the results of the given program location, or
+slice forward to determine which instructions are affected by the results of the
+given program location. One key feature of our slicing implementation is that
+users can control where and when to stop slicing through a set of call back
+functions.
+
+\item [Stack Analysis] Determines whether a register points to the stack and
+which stack location the register points to, when it does point to the stack.
+
+\item [Symbolic Expansion and Evaluation] convert a set of instructions to
+several symbolic expressions. Each symbolic expression represents the overall effects of
+these instructions on a register or a memory location.
+
+\item [Register Liveness] Determines a register is live or not at a program
+location. A register is live at a program location if it will be used later in the program before its
+content is overwritten. 
 \end{itemize}