Massive dataflowAPI manual writing

dataflowAPI/doc/AbsLocs.tex

@@ -1,2 +1,5 @@
-\section{Abstract Locations and Regions}
+\subsection{Abstract Locations and Regions}
 \label{sec:abslocs}
+
+
+\subsection{Class AbsRegionConverter}

dataflowAPI/doc/Abstractions.tex

@@ -5,12 +5,26 @@ \section{Abstractions}
 From these, it provides dataflow facts in a variety of forms. The key abstractions used by DataflowAPI are:
 
 \begin{itemize}
-\item[Abstract Location] Represents a register or memory location (cite)
-\item[Abstract Region] Represents a set of abstract locations (cite)
+\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.
+\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.
-\item[Assignment] Represents a single data dependency 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[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[AST] Represents the symbolic expansion of an instruction's full semantics
 \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}
+\end{itemize}
+
+

dataflowAPI/doc/Assignment.tex

@@ -1,2 +1,4 @@
-\section{Assignments}
+\subsection{Assignments}
 \label{sec:assign}
+\subsection{Class AssignmentConverter}
+

dataflowAPI/doc/Graph.tex

@@ -1,2 +1,185 @@
-\section{Graphs, Nodes, and Edges}
+\subsection{Graph}
+\definedin{common/h/Graph.h}
 \label{sec:graph}
+
+We provide a generic graph interface, which allows users adding, deleting,
+iterating nodes and edges in a graph. Our slicing algorithms are implemented
+upon this graph interface, so users can inherit the defined classes for
+customization.
+
+\begin{apient}
+typedef boost::shared_ptr<Graph> Graph::Ptr;
+\end{apient}
+\apidesc{Shared pointer for Graph}
+
+\begin{apient}
+virtual void Graph::entryNodes(NodeIterator &begin, NodeIterator &end);
+\end{apient}
+\apidesc{The entry nodes (nodes without any incoming edges) of the graph.}
+
+    // If you want to traverse the graph backwards start here.
+\begin{apient}
+virtual void Graph::exitNodes(NodeIterator &begin, NodeIterator &end);
+\end{apient}
+\apidesc{The exit nodes (nodes without any outgoing edges) of the graph.}
+
+\begin{apient}
+virtual void Graph::allNodes(NodeIterator &begin, NodeIterator &end);
+\end{apient}
+\apidesc{Iterate all nodes in the graph.}
+
+
+\begin{apient}
+class Graph::NodePredicate;
+typedef boost::shared_ptr<Graph::NodePredicate> Graph::NodePredicate::Ptr;
+virtual bool Graph::NodePredicate::predicate(const NodePtr &node) = 0;
+
+\end{apient}
+\apidesc{Interface class for predicate-based searches. Users can inherit this
+class to specify the functor to use as a predicate to iterate over nodes in the
+graph.}
+
+
+\begin{apient}
+virtual bool Graph::find(Address addr, NodeIterator &begin, NodeIterator &end);
+
+typedef bool (*NodePredicateFunc)(const NodePtr &node, void *user_arg);
+virtual bool Graph::find(NodePredicate::Ptr, NodeIterator &begin, NodeIterator &end);
+
+virtual bool Graph::find(NodePredicateFunc, void *user_arg, NodeIterator &begin, NodeIterator &end);
+\end{apient}
+\apidesc{Find all nodes satisfying the given conditions} 
+
+\begin{apient}
+bool Graph::printDOT(const std::string& fileName);
+\end{apient}
+\apidesc{Output the graph in dot format.}
+
+\begin{apient}
+static Graph::Ptr Graph::createGraph();
+\end{apient}
+\apidesc{Return an empty graph.}
+
+\begin{apient}
+void Graph::insertPair(NodePtr source, NodePtr target, EdgePtr edge = EdgePtr());
+\end{apient}
+\apidesc{Insert an pair of node into the graph and create a new edge \code{edge} from
+\code{source} to \code{target}.}
+
+\begin{apient}
+virtual void Graph::insertEntryNode(NodePtr entry);
+virtual void Graph::insertExitNode(NodePtr exit);
+\end{apient}
+\apidesc{Insert a node as an entry/exit node}
+
+\begin{apient}
+virtual void Graph::markAsEntryNode(NodePtr entry);
+virtual void Graph::markAsExitNode(NodePtr exit);
+\apidesc{Mark a node that has been added to this graph as an entry/exit node.}
+
+
+\begin{apient}
+void Graph::deleteNode(NodePtr node);
+void Graph::addNode(NodePtr node);
+\end{apient}
+\apidesc{Delete / Add a node.}
+
+\begin{apient}
+bool Graph::isEntryNode(NodePtr node);
+bool Graph::isExitNode(NodePtr node);
+\end{apient}
+\apidesc{Check whether a node is an entry / exit node}
+
+\begin{apient}
+void Graph::clearEntryNodes();
+void Graph::clearExitNodes();
+\end{apient}
+\apidesc{Clear the marking of entry / exit nodes. Note that the nodes are not
+deleted from the graph.}
+
+\begin{apient}
+unsigned Graph::size() const;
+\end{apient}
+\apidesc{Return the number of nodes in the graph.}
+
+\subsection{Node}
+\definedin{common/h/Node.h}
+
+\begin{apient}
+typedef boost::shared_ptr<Node> Node::Ptr;
+\end{apient}
+\apidesc{shared pointer for Node}
+
+\begin{apient}
+void Node::ins(EdgeIterator &begin, EdgeIterator &end);
+void Node::outs(EdgeIterator &begin, EdgeIterator &end);
+\end{apient}
+\apidesc{Iterate over incoming/outgoing edges of this node.}
+
+\begin{apient}
+void Node::ins(NodeIterator &begin, NodeIterator &end);
+void Node::outs(NodeIterator &begin, NodeIterator &end);
+\end{apient}
+\apidesc{Iterate over adjacent nodes connected with incoming/outgoing edges of
+this node}.
+
+\begin{apient}
+bool Node::hasInEdges(); 
+bool Node::hasOutEdges();
+\end{apient}
+\apidesc{Return \code{true} if this node has incoming/outgoing edges.}
+
+\begin{apient}
+void Node::deleteInEdge(EdgeIterator e);
+void Node::deleteOutEdge(EdgeIterator e);
+\end{apient}
+\apidesc{Delete an incoming/outgoing edge.}
+
+\begin{apient}
+virtual Address Node::addr() const;
+\end{apient}
+\apidesc{Return the address of this node.}
+
+\begin{apient}    
+virtual std::string Node::format() const = 0;
+\end{apient}
+\apidesc{Return the string representation.}
+
+\begin{apient}
+class NodeIterator
+\end{apient}
+\apidesc{Iterator for nodes. Common iterator operations including \code{++},
+\code{--}, and dereferencing are supported.}
+
+
+\subsection{Edge}
+\definedin{common/h/Edge.h}
+
+\begin{apient}
+typedef boost::shared_ptr<Edge> Edge::Ptr;
+\end{apient}
+\apidesc{Shared pointer for \code{Edge}.}
+
+\begin{apient}
+static Edge::Ptr Edge::createEdge(const Node::Ptr source, const Node::Ptr target);
+\end{apient}
+\apidesc{Create a new directed edge from \code{source} to \code{target}.}
+
+\begin{apient}
+Node::Ptr Edge::source() const; 
+Node::Ptr Edge::target() const;
+\end{apient}
+\apidesc{Return the source / target node.}
+
+\begin{apient}
+void Edge::setSource(Node::Ptr source); 
+void Edge::setTarget(Node::Ptr target);
+\end{apient}
+\apidesc{Set the source / target node.}
+
+\begin{apient}
+class EdgeIterator
+\end{apient}
+\apidesc{Iterator for edges. Common iterator operations including \code{++},
+\code{--}, and dereferencing are supported.}
+

dataflowAPI/doc/Intro.tex

@@ -1,11 +1,13 @@
 \section{Introduction}
 \label{sec:intro}
 
-DataFlowAPI aggregates a collection of dataflow analysis algorithms that are useful in Dyninst development into a single library. Currently, these algorithms include:
+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:
 \begin{itemize}
 \item Slicing
 \item Stack Analysis
 \item Instruction Semantics
 \item Symbolic Expansion and Evaluation
 \item Register Liveness
-\end{itemize}
+\end{itemize}