\section{Modification API Reference}
\label{sec-modification-api}

This section describes the modification interface of PatchAPI. While
PatchAPI's main goal is to allow users to insert new code into a
program, a secondary goal is to allow safe modification of the
original program code as well. 

To modify the binary, a user interacts with the \code{PatchModifier}
class to manipulate a PatchAPI CFG. CFG modifications are then
instantiated as new code by the PatchAPI. For example, if PatchAPI is
being used as part of Dyninst, executing a \code{finalizeInsertionSet}
will generate modified code. 

The three key benefits of the PatchAPI modification interface are
abstraction, safety, and interactivity. We use the CFG as a mechanism
for transforming binaries in a platform-independent way that requires
no instruction-level knowledge by the user. These transformations are
limited to ensure that the CFG can always be used to instantiate code,
and thus the user can avoid unintended side-effects of
modification. Finally, modifications to the CFG are represented in
that CFG, allowing users to iteratively combine multiple CFG
transformations to achieve their goals. 

Since modification can modify the CFG, it may invalidate any analyses
the user has performed over the CFG. We suggest that users take
advantage of the callback interface described in Section
\ref{sec-3.2.7} to update any such analysis information. 

The PatchAPI modification capabilities are currently in beta; if you
experience any problems or bugs, please contact \code{bugs@dyninst.org}.

Many of these methods return a boolean type; true indicates a
successful operation, and false indicates a failure. For methods that
return a pointer, a \code{NULL} return value indicates a failure. 

\begin{apient}
bool redirect(PatchEdge *edge, PatchBlock *target);
\end{apient}
\apidesc{Redirects the edge specified by \code{edge} to a new target
  specified by \code{target}. In the current implementation, the edge
  may not be indirect.}

\begin{apient}
PatchBlock *split(PatchBlock *orig, Address addr, 
                  bool trust = false,
                  Address newlast = (Address) -1);
\end{apient}
\apidesc{Splits the block specified by \code{orig}, creating a new
  block starting at \code{addr}. If \code{trust} is true, we do not
  verify that \code{addr} is a valid instruction address; this may be
  useful to reduce overhead. If \code{newlast} is not -1, we use it as
  the last instruction address of the first block. All Points are
  updated to belong to the appropriate block. The second block is
  returned.}

\begin{apient}
bool remove(std::vector<PatchBlock *> &blocks, bool force = true)
\end{apient}
\apidesc{Removes the blocks specified by \code{blocks} from the
  CFG. If \code{force} is true, blocks are removed even if they have
  incoming edges; this may leave the CFG in an unsafe state but may be
  useful for reducing overhead.}

\begin{apient}
bool remove(PatchFunction *func)
\end{apient}
\apidesc{Removes \code{func} and all of its non-shared blocks from the
  CFG; any shared blocks remain.}

\begin{apient}
class InsertedCode {
  typedef boost::shared_ptr<...> Ptr;
  PatchBlock *entry();
  const std::vector<PatchEdge *> &exits();
  const std::set<PatchBlock *> &blocks();
}

InsertedCode::Ptr insert(PatchObject *obj, SnippetPtr snip, Point *point);
InsertedCode::Ptr insert(PatchObject *obj, void *start, unsigned size);
\end{apient}
\apidesc{Methods for inserting new code into a CFG. The
  \code{InsertedCode} structure represents a CFG subgraph generated by
  inserting new code; the graph has a single entry point and multiple
  exits, represented by edges to the sink node. The first
  \code{insert} call takes a PatchAPI Snippet structure and a Point
  that is used to generate that Snippet; the point is only passed
  through to the snippet code generator and thus may be \code{NULL} if
  the snippet does not use Point information. The second \code{insert}
  call takes a raw code buffer.}





