Add dyninstAPI/BPatch_flowGraph.h

dyninst · Apr 3, 2024 · 634d989 · 634d989
1 parent 9bc9412
commit 634d989
Show file tree

Hide file tree

Showing 4 changed files with 116 additions and 84 deletions.
diff --git a/docs/dyninstAPI/developer/API.rst b/docs/dyninstAPI/developer/API.rst
@@ -18,6 +18,7 @@ DyninstAPI
   BPatch_basicBlockLoop.h
   BPatch_collections.h
   BPatch_dll.h
+  BPatch_flowGraph.h
   BPatch_libInfo.h
   BPatch_memoryAccessAdapter.h
   BPatch_private.h

diff --git a/docs/dyninstAPI/developer/BPatch_flowGraph.h.rst b/docs/dyninstAPI/developer/BPatch_flowGraph.h.rst
@@ -0,0 +1,37 @@
+.. _`sec-dev:BPatch_flowGraph.h`:
+
+BPatch_flowGraph.h
+##################
+
+.. cpp:namespace:: dev
+
+.. cpp:class:: BPatch_flowGraph : public Dyninst::AnnotatableSparse
+
+  .. cpp:member:: std::set<BPatch_basicBlockLoop*> *loops
+
+    set of loops contained in control flow graph
+
+  .. cpp:member:: std::set<BPatch_basicBlock*> allBlocks
+
+    set of all basic blocks that control flow graph has
+
+  .. cpp:member:: BPatch_loopTreeNode *loopRoot
+
+    root of the tree of loops
+
+  .. cpp:member:: std::set<BPatch_edge*> backEdges
+
+    set of back edges
+
+  .. cpp:member:: bool isDominatorInfoReady
+
+    flag that keeps whether dominator info is initialized
+
+  .. cpp:member:: bool isPostDominatorInfoReady
+
+    flag that keeps whether postdominator info is initialized
+
+  .. cpp:member:: bool isSourceBlockInfoReady
+
+    flag that keeps whether source block info is initialized
+
diff --git a/docs/dyninstAPI/public/BPatch_flowGraph.h.rst b/docs/dyninstAPI/public/BPatch_flowGraph.h.rst
@@ -3,58 +3,104 @@
 BPatch_flowGraph.h
 ##################
 
-.. cpp:class:: BPatch_flowGraph
+.. note::
+
+  Dyninst is not always able to generate a correct flow graph
+  in the presence of indirect jumps. If a function has a case statement or
+  indirect jump instructions, the targets of the jumps are found by
+  searching instruction patterns (peep-hole). The instruction patterns
+  generated are compiler specific and the control flow graph analyses
+  include only the ones we have seen. During the control flow graph
+  generation, if a pattern that is not handled is used for case statement
+  or multi-jump instructions in the function address space, the generated
+  control flow graph may not be complete.
+
+.. cpp:class:: BPatch_flowGraph : public Dyninst::AnnotatableSparse
    
-  The **BPatch_flowGraph** class represents the control flow graph of a
-  function. It provides methods for discovering the basic blocks and loops
+  **The control flow graph of a function**
+
+  It provides methods for discovering the basic blocks and loops
   within the function (using which a caller can navigate the graph). A
   BPatch_flowGraph object can be obtained by calling the getCFG method of
   a BPatch_function object.
 
-  .. cpp:function:: bool containsDynamicCallsites()
+  .. cpp:function:: BPatch_addressSpace *getAddSpace() const
+  .. cpp:function:: AddressSpace *getllAddSpace() const
+  .. cpp:function:: BPatch_function *getFunction() const
+  .. cpp:function:: BPatch_module *getModule() const
+  .. cpp:function:: BPatch_basicBlock *findBlock(block_instance *b)
+  .. cpp:function:: BPatch_edge *findEdge(edge_instance *e)
+  .. cpp:function:: void invalidate()
+
+      invoked when additional parsing takes place
+
+  .. cpp:function:: ~BPatch_flowGraph()
+
+  .. cpp:function:: bool getAllBasicBlocks(BPatch_Set<BPatch_basicBlock*> &blocks)
+
+    returns the set of all basic blocks in the CFG
+
+  .. cpp:function:: bool getAllBasicBlocks(std::set<BPatch_basicBlock *> &blocks)
 
-    Return true if the control flow graph contains any dynamic call sites
-    (e.g., calls through a function pointer).
+  returns the set of all basic blocks in the CFG
+
+  .. cpp:function:: bool getEntryBasicBlock(BPatch_Vector<BPatch_basicBlock*> &blocks)
+
+    returns the vector of entry basic blocks to CFG
+
+  .. cpp:function:: bool getExitBasicBlock(BPatch_Vector<BPatch_basicBlock*> &blocks)
+
+    returns the vector of exit basic blocks to CFG
+
+  .. cpp:function:: BPatch_basicBlock *findBlockByAddr(Dyninst::Address addr)
+
+    Find the basic block within this flow graph that contains addr. Returns
+    NULL on failure. This method is inefficient but guaranteed to succeed if
+    addr is present in any block in this CFG.
 
-  .. cpp:function:: void getAllBasicBlocks(std::set<BPatch_basicBlock*>&)
+    .. warning: this method is slow!
 
-  .. cpp:function:: void getAllBasicBlocks(BPatch_Set<BPatch_basicBlock*>&)
+  .. cpp:function:: bool getLoops(BPatch_Vector<BPatch_basicBlockLoop*> &loops)
 
-    Fill the given set with pointers to all basic blocks in the control flow
-    graph. BPatch_basicBlock is described in section 4.17.
+    Returns in ``loops`` the natural (single entry) loops in the control flow graph.
 
-  .. cpp:function:: void getEntryBasicBlock(std::vector<BPatch_basicBlock*>&)
+  .. cpp:function:: bool getOuterLoops(BPatch_Vector<BPatch_basicBlockLoop*> &loops)
 
-    Fill the given vector with pointers to all basic blocks that are entry
-    points to the function. BPatch_basicBlock is described in section 4.17.
+    Returns in ``loops`` the natural (single entry) outer loops in the control flow graph.
 
-  .. cpp:function:: void getExitBasicBlock(std::vector<BPatch_basicBlock*>&)
+  .. cpp:function:: bool createSourceBlocks()
 
-    Fill the given vector with pointers to all basic blocks that are exit
-    points of the function. BPatch_basicBlock is described in section 4.17.
+    creates the source line blocks of all blocks in CFG. without calling this method line info is not available
 
-  .. cpp:function:: void getLoops(std::vector<BPatch_basicBlockLoop*>&)
+  .. cpp:function:: void fillDominatorInfo()
 
-    Fill the given vector with a list of all natural (single entry) loops in
-    the control flow graph.
+    fills the dominator and immediate-dom information of basic blocks. without calling this method dominator info is not available
 
-  .. cpp:function:: void getOuterLoops(std::vector<BPatch_basicBlockLoop*>&)
+  .. cpp:function:: void fillPostDominatorInfo()
 
-    Fill the given vector with a list of all natural (single entry) outer
-    loops in the control flow graph.
+    same as :cpp:func:`fillDominatorInfo`, but for postdominatorimmediate-postdom info
 
-  .. cpp:function:: BPatch_loopTreeNode *getLoopTree()
+  .. cpp:function:: BPatch_loopTreeNode * getLoopTree()
 
     Return the root node of the tree of loops in this flow graph.
 
-  .. cpp:enum:: BPatch_procedureLocation
-  .. cpp:enumerator:: BPatch_procedureLocation::BPatch_locLoopEntry
-  .. cpp:enumerator:: BPatch_procedureLocation::BPatch_locLoopExit
-  .. cpp:enumerator:: BPatch_procedureLocation::BPatch_locLoopStartIter
-  .. cpp:enumerator:: BPatch_procedureLocation::BPatch_locLoopEndIter
+  .. cpp:function:: bool containsDynamicCallsites()
+
+    Checks if the control flow graph contains any dynamic call sites (e.g., calls through a function pointer).
+
+  .. cpp:function:: void printLoops()
+
+    for debugging, print loops with line numbers to stderr
+
+  .. cpp:function:: BPatch_basicBlockLoop * findLoop(const char *name)
+  .. cpp:function:: bool isValid()
+  .. cpp:function:: BPatch_Vector<BPatch_point*>* findLoopInstPoints(const BPatch_procedureLocation loc, \
+                                                                     Patch_basicBlockLoop *loop)
 
-  .. cpp:function:: std::vector<BPatch_point*> *findLoopInstPoints( \
-       const BPatch_procedureLocation loc, BPatch_basicBlockLoop *loop);
+    find instrumentation points specified by loc, add to points
+
+  .. cpp:function:: std::vector<BPatch_point*> *findLoopInstPoints(const BPatch_procedureLocation loc, \
+                                                                   BPatch_basicBlockLoop *loop)
 
     Find instrumentation points for the given loop that correspond to the
     given location: loop entry, loop exit, the start of a loop iteration and
@@ -63,20 +109,3 @@ BPatch_flowGraph.h
     iteration of a loop and after the last iteration.
     BPatch_locLoopStartIter and BPatch_locLoopEndIter respectively execute
     at the beginning and end of each loop iteration.
-
-  .. cpp:function:: BPatch_basicBlock* findBlockByAddr(Dyninst::Address addr);
-
-    Find the basic block within this flow graph that contains addr. Returns
-    NULL on failure. This method is inefficient but guaranteed to succeed if
-    addr is present in any block in this CFG.
-
-    .. note::
-       Dyninst is not always able to generate a correct flow graph
-       in the presence of indirect jumps. If a function has a case statement or
-       indirect jump instructions, the targets of the jumps are found by
-       searching instruction patterns (peep-hole). The instruction patterns
-       generated are compiler specific and the control flow graph analyses
-       include only the ones we have seen. During the control flow graph
-       generation, if a pattern that is not handled is used for case statement
-       or multi-jump instructions in the function address space, the generated
-       control flow graph may not be complete.
diff --git a/dyninstAPI/h/BPatch_flowGraph.h b/dyninstAPI/h/BPatch_flowGraph.h
@@ -51,12 +51,6 @@ class edge_instance;
 
 typedef BPatch_basicBlockLoop BPatch_loop;
 
-/** class which represents the control flow graph of a function
-  * in a executable code. 
-  *
-  * @see BPatch_basicBlock
-  * @see BPatch_basicBlockLoop
-  */
 namespace Dyninst {
     namespace PatchAPI{
         class PatchLoop;
@@ -69,8 +63,7 @@ class BPATCH_DLL_EXPORT BPatch_flowGraph :
   friend class BPatch_edge;
   friend class BPatch_function;
   friend class dominatorCFG;
-  friend class func_instance; // This is illegal here... keeps us from having to
-                            // have a public constructor...  PDSEP
+  friend class func_instance;
   friend void dfsCreateLoopHierarchy(BPatch_loopTreeNode * parent,
                                      BPatch_Vector<BPatch_basicBlockLoop *> &loops,
                                      std::string level);
@@ -93,60 +86,39 @@ class BPATCH_DLL_EXPORT BPatch_flowGraph :
 
   BPatch_basicBlock *findBlock(block_instance *b);
   BPatch_edge *findEdge(edge_instance *e);
-  void invalidate(); // invoked when additional parsing takes place
-
-  //  Functions for use by Dyninst users
+  void invalidate();
 
   ~BPatch_flowGraph();
 
-  /** returns the set of all basic blocks in the CFG */
   bool getAllBasicBlocks(BPatch_Set<BPatch_basicBlock*> &blocks); 
   bool getAllBasicBlocks(std::set<BPatch_basicBlock *> &blocks);
 
-  /** returns the vector of entry basic blocks to CFG */
   bool getEntryBasicBlock(BPatch_Vector<BPatch_basicBlock*> &blocks);
 
-  /** returns the vector of exit basic blocks to CFG */
   bool getExitBasicBlock(BPatch_Vector<BPatch_basicBlock*> &blocks);
 
-  /** Finds the block containing a specific instruction. Warning:
-      this method is slow! **/
   BPatch_basicBlock *findBlockByAddr(Dyninst::Address addr);
 
-  /** returns the vector of loops in CFG */
   bool getLoops(BPatch_Vector<BPatch_basicBlockLoop*> &loops);
 
-  /** returns a vector of outer loops in the CFG */
   bool getOuterLoops(BPatch_Vector<BPatch_basicBlockLoop*> &loops);
 
-  /** creates the source line blocks of all blocks in CFG.
-   * without calling this method line info is not available
-   */
   bool createSourceBlocks();
 
-  /** fills the dominator and immediate-dom information of basic blocks.
-   * without calling this method dominator info is not available
-   */
   void fillDominatorInfo();
 
-  /** same as above, but for postdominator/immediate-postdom info 
-   */
   void fillPostDominatorInfo();
 
-  /** return root of loop hierarchy  */
   BPatch_loopTreeNode * getLoopTree();
 
-  /** returns true if the cfg contains dynamic callsites */
   bool containsDynamicCallsites();
 
-  // for debugging, print loops with line numbers to stderr
   void printLoops();
 
   BPatch_basicBlockLoop * findLoop(const char *name);
 
   bool isValid(); 
 
-  /** find instrumentation points specified by loc, add to points*/
   BPatch_Vector<BPatch_point*> * 
       findLoopInstPoints(const BPatch_procedureLocation loc, 
                           BPatch_basicBlockLoop *loop);
@@ -158,25 +130,18 @@ class BPATCH_DLL_EXPORT BPatch_flowGraph :
   //  BPatch_process *bproc;
   BPatch_module *mod;
 
-  /** set of loops contained in control flow graph */
   std::set<BPatch_basicBlockLoop*> *loops;
 
-  /** set of all basic blocks that control flow graph has */
   std::set<BPatch_basicBlock*> allBlocks;
 
-  /** root of the tree of loops */
   BPatch_loopTreeNode *loopRoot;
 
-  /** set of back edges */
   std::set<BPatch_edge*> backEdges;
 
-  /** flag that keeps whether dominator info is initialized*/
   bool isDominatorInfoReady;
 
-  /** flag that keeps whether postdominator info is initialized*/
   bool isPostDominatorInfoReady;
 
-  /** flag that keeps whether source block info is initialized*/
   bool isSourceBlockInfoReady;
 
   bool createBasicBlocks();