Add dyninstAPI/src/BPatch_basicBlock.C

docs/dyninstAPI/developer/BPatch_basicBlock.h.rst

@@ -57,3 +57,6 @@ BPatch_basicBlock.h
   .. cpp:function:: void setlowlevel_block(block_instance *b)
   .. cpp:function:: void getAllPoints(std::vector<BPatch_point*>& allPoints)
 
+  .. cpp:function:: BPatch_point* findExitPoint()
+
+    This should be edge instrumentation.

docs/dyninstAPI/public/BPatch_basicBlock.h.rst

@@ -7,7 +7,7 @@ BPatch_basicBlock.h
    
   **Machine code basic blocks**
 
-  Users should not create basic blocks using its constructor. It is not safe.
+  .. caution:: Users should not create basic blocks using its constructor. It is not safe.
 
   Basic blocks are used for reading purposes, not for inserting a new code to the machine
   executable other than instrumentation code.
@@ -16,67 +16,75 @@ BPatch_basicBlock.h
   .. cpp:function:: block_instance *block() const
   .. cpp:function:: BPatch_function *func() const
   .. cpp:function:: func_instance *ifunc() const
+
   .. cpp:function:: BPatch_point *convertPoint(instPoint *pt)
+
+    Returns the ``BPatch_point`` for ``pt``.
+
+    Returns ``NULL`` if ``pt`` isn't in this block.
+
   .. cpp:function:: BPatch_function *getCallTarget()
   .. cpp:function:: BPatch_flowGraph * getFlowGraph() const
 
   .. cpp:function:: void getSources(std::vector<BPatch_basicBlock*>&)
 
-    Fills the given vector with the list of predecessors for this basic
+    Returns the predecessors for this basic
     block (i.e, basic blocks that have an outgoing edge in the control flow
     graph leading to this block).
 
   .. cpp:function:: void getTargets(std::vector<BPatch_basicBlock*>&)
 
-    Fills the given vector with the list of successors for this basic block
+    Returns the successors for this basic block
     (i.e, basic blocks that are the destinations of outgoing edges from this
     block in the control flow graph).
 
   .. cpp:function:: bool dominates(BPatch_basicBlock*)
 
-    Returns true if the argument is pre-dominated in the
+    Checks if the argument is pre-dominated in the
     control flow graph by this block, and false if it is not.
 
   .. cpp:function:: BPatch_basicBlock* getImmediateDominator()
 
-    Return the basic block that immediately pre-dominates this block in the
+    Returns the basic block that immediately pre-dominates this block in the
     control flow graph.
 
   .. cpp:function:: void getImmediateDominates(std::vector<BPatch_basicBlock*>&)
 
-    Fill the given vector with a list of pointers to the basic blocks that
-    are immediately dominated by this basic block in the control flow graph.
+    Returns the basic blocks that are immediately dominated by this basic block in the control flow graph.
 
   .. cpp:function:: void getAllDominates(std::set<BPatch_basicBlock*>&)
 
-      Returns all basic blocks dominated by the basic block
+      Returns all basic blocks dominated by the basic block.
+
+      Does not return duplicates even if some points belong to multiple categories.
 
   .. cpp:function:: void getAllDominates(BPatch_Set<BPatch_basicBlock*>&)
 
       Returns all basic blocks dominated by the basic block
 
   .. cpp:function:: bool getSourceBlocks(std::vector<BPatch_sourceBlock*>&)
 
-    Fill the given vector with pointers to the source blocks contributing to
-    this basic block’s instruction sequence.
+    Returns the source blocks contributing to this basic block’s instruction sequence.
 
   .. cpp:function:: int getBlockNumber()
 
-    Return the ID number of this basic block. The ID numbers are consecutive
-    from 0 to *n-1,* where *n* is the number of basic blocks in the flow
+    Returns the ID number of this basic block.
+
+    The ID numbers are consecutive
+    from ``0`` to ``n-1``, where ``n`` is the number of basic blocks in the flow
     graph to which this basic block belongs.
 
   .. cpp:function:: bool isEntryBlock()
 
-    Returns true if this basic block is an entry block into a function.
+    Checks if this basic block is an entry block into a function.
 
   .. cpp:function:: bool isExitBlock()
 
-    Returns true if this basic block is an exit block of a function.
+    Checks if this basic block is an exit block of a function.
 
   .. cpp:function:: unsigned size()
 
-    Return the size of a basic block.
+    Returns the size of a basic block.
 
     The size is defined as the difference between the end address and the start address
     of the basic block.
@@ -88,7 +96,7 @@ BPatch_basicBlock.h
 
   .. cpp:function:: unsigned long getLastInsnAddress()
 
-    Return the address of the last instruction in a basic block.
+    Returns the address of the last instruction in a basic block.
 
   .. cpp:function:: unsigned long getEndAddress()
 
@@ -105,15 +113,15 @@ BPatch_basicBlock.h
 
   .. cpp:function:: BPatch_point* findExitPoint()
 
-      Return point at the start of the basic block
+      Returns point at the start of the basic block
 
   .. cpp:function:: BPatch_Vector<BPatch_point*>* findPoint(const BPatch_Set<BPatch_opCode>& ops)
 
-      Return the points within the basic block
+      Returns in ``ops`` the points within the basic block.
 
-  .. cpp:function:: BPatch_Vector<BPatch_point*> * findPoint(const std::set<BPatch_opCode>& ops)
+  .. cpp:function:: BPatch_Vector<BPatch_point*>* findPoint(const std::set<BPatch_opCode>& ops)
 
-      Return the points within the basic block
+      Returns in ``ops`` the points within the basic block.
 
   .. cpp:function:: BPatch_Vector<BPatch_point*> * findPoint(bool(*filter)(Dyninst::InstructionAPI::Instruction))
   .. cpp:function:: BPatch_point * findPoint(Dyninst::Address addr)
@@ -125,7 +133,7 @@ BPatch_basicBlock.h
   .. cpp:function:: bool getInstructions(std::vector <std::pair<Dyninst::InstructionAPI::Instruction,Address> >&)
 
     Fills the given vector with InstructionAPI Instruction objects
-    representing the instructions in this basic block, and returns true if
+    representing the instructions in this basic block, and Checks if
     successful. See the InstructionAPI Programmer’s Guide for details. The
     second call also returns the address each instruction starts at.
 

docs/dyninstAPI/public/BPatch_basicBlockLoop.h.rst

@@ -13,12 +13,12 @@ BPatch_basicBlockLoop.h
 
   .. cpp:function:: bool containsAddress(unsigned long addr)
 
-    Return true if addr is contained within any of the basic blocks that
+    Checks if addr is contained within any of the basic blocks that
     compose this loop, excluding the block of any of its sub-loops.
 
   .. cpp:function:: bool containsAddressInclusive(unsigned long addr)
 
-    Return true if addr is contained within any of the basic blocks that
+    Checks if addr is contained within any of the basic blocks that
     compose this loop, or in the blocks of any of its sub-loops.
 
   .. cpp:function:: int getBackEdges(std::vector<BPatch_edge *> &edges)
@@ -32,38 +32,38 @@ BPatch_basicBlockLoop.h
     Returns the number of entry blocks of this loop and adds those blocks to
     the entries vector. An irreducible loop can have multiple entry blocks.
 
-  .. cpp:function:: bool getContainedLoops(std::vector<BPatch_basicBlockLoop*>&)
+  .. cpp:function:: bool getContainedLoops(std::vector<BPatch_basicBlockLoop*>& loops)
 
-    Fill the given vector with a list of the loops nested within this loop.
+    Returns the loops nested within this loop.
 
   .. cpp:function:: bool getOuterLoops(BPatch_Vector<BPatch_basicBlockLoop*> &loops)
 
-    Fill the given vector with a list of the outer loops nested within this
+    Returns the outer loops nested within this
     loop.
 
   .. cpp:function:: bool getLoopBasicBlocks(BPatch_Vector<BPatch_basicBlock*> &blocks)
 
-    Fill the given vector with a list of all basic blocks that are part of
+    Returns all basic blocks that are part of
     this loop.
 
   .. cpp:function:: bool getLoopBasicBlocksExclusive(BPatch_Vector<BPatch_basicBlock*> &blocks)
 
-    Fill the given vector with a list of all basic blocks that are part of
+    Returns all basic blocks that are part of
     this loop but not its sub-loops.
 
   .. cpp:function:: bool hasBlock(BPatch_basicBlock *b)
 
-    Return true if this loop or any of its sub-loops contain b, false
+    Checks if this loop or any of its sub-loops contain b, false
     otherwise.
 
   .. cpp:function:: bool hasBlockExclusive(BPatch_basicBlock *b)
 
-    Return true if this loop, excluding its sub-loops, contains b, false
+    Checks if this loop, excluding its sub-loops, contains b, false
     otherwise.
 
   .. cpp:function:: bool hasAncestor(BPatch_basicBlockLoop*)
 
-    Return true if this loop is nested within the given loop (the given loop
+    Checks if this loop is nested within the given loop (the given loop
     is one of its ancestors in the tree of loops).
 
   .. cpp:function:: BPatch_flowGraph * getFlowGraph()

dyninstAPI/src/BPatch_basicBlock.C

@@ -71,7 +71,6 @@ BPatch_basicBlock::BPatch_basicBlock(block_instance *ib, BPatch_flowGraph *fg):
 #endif
 }
 
-//destructor of the class BPatch_basicBlock
 BPatch_basicBlock::~BPatch_basicBlock(){
   if (immediatePostDominates)
     delete immediatePostDominates;
@@ -102,8 +101,6 @@ void source_helper(ParseAPI::Edge* e,
 }
 
 
-// returns the predecessors of the basic block, provided they are in the same
-// function, since our CFGs at the BPatch level are intraprocedural
 void BPatch_basicBlock::getSources(BPatch_Vector<BPatch_basicBlock*>& srcs){
   //  BPatch_basicBlock *b;
   std::vector<block_instance *> in_blocks;
@@ -124,7 +121,6 @@ void BPatch_basicBlock::getSources(BPatch_Vector<BPatch_basicBlock*>& srcs){
 			    func));
 }
 
-//returns the successors of the basic block in a set
 void BPatch_basicBlock::getTargets(BPatch_Vector<BPatch_basicBlock*>& tgrts){
   BPatch_basicBlock *b;
   std::vector<block_instance *> out_blocks;
@@ -139,7 +135,6 @@ void BPatch_basicBlock::getTargets(BPatch_Vector<BPatch_basicBlock*>& tgrts){
   }
 }
 
-//returns the dominates of the basic block in a set
 void BPatch_basicBlock::getImmediateDominates(BPatch_Vector<BPatch_basicBlock*>& imds){
   flowGraph->fillDominatorInfo();
 
@@ -163,7 +158,6 @@ void BPatch_basicBlock::getImmediatePostDominates(BPatch_Vector<BPatch_basicBloc
   return;
 }
 
-//returns the dominates of the basic block in a set
 void
 BPatch_basicBlock::getAllDominates(std::set<BPatch_basicBlock*>& buffer){
   flowGraph->fillDominatorInfo();
@@ -208,7 +202,6 @@ BPatch_basicBlock::getAllPostDominates(BPatch_Set<BPatch_basicBlock*>& buffer){
 }
 
 
-//returns the immediate dominator of the basic block
 BPatch_basicBlock* BPatch_basicBlock::getImmediateDominator(){
   flowGraph->fillDominatorInfo();
 
@@ -221,7 +214,6 @@ BPatch_basicBlock* BPatch_basicBlock::getImmediatePostDominator(){
   return immediatePostDominator;
 }
 
-//returns whether this basic block dominates the argument
 bool BPatch_basicBlock::dominates(BPatch_basicBlock* bb){
   if(!bb)
     return false;
@@ -260,8 +252,6 @@ bool BPatch_basicBlock::postdominates(BPatch_basicBlock* bb){
   return false;
 }
 
-//returns the source block corresponding to the basic block
-//which is created looking at the machine code.
 bool
 BPatch_basicBlock::getSourceBlocks(BPatch_Vector<BPatch_sourceBlock*>& sBlocks)
 {
@@ -277,12 +267,10 @@ BPatch_basicBlock::getSourceBlocks(BPatch_Vector<BPatch_sourceBlock*>& sBlocks)
   return true;
 }
 
-//returns the block number of the basic block
 int BPatch_basicBlock::getBlockNumber() {
   return iblock->id();
 }
 
-// returns the range of addresses of the code for the basic block
 bool BPatch_basicBlock::getAddressRange(void*& _startAddress,
                                            void*& _lastInsnAddress)
 {
@@ -337,16 +325,6 @@ ostream& operator<<(ostream& os,BPatch_basicBlock& bb)
   return os;
 }
 
-/*
- * BPatch_basicBlock::findPoint (based on VG 09/05/01)
- *
- * Returns a vector of the instrumentation points from a basic block that is
- * identified by the parameters, or returns NULL upon failure.
- * (Points are sorted by address in the vector returned.)
- *
- * ops          The points within the basic block to return. A set of op codes
- *              defined in BPatch_opCode (BPatch_point.h)
- */
 using namespace Dyninst::InstructionAPI;
 bool isLoad(Instruction i)
 {
@@ -430,7 +408,6 @@ BPatch_point* BPatch_basicBlock::findEntryPoint()
                                                        BPatch_locBasicBlockEntry);
 }
 
-// This should be edge instrumentation...
 BPatch_point* BPatch_basicBlock::findExitPoint()
 {
   return flowGraph->getAddSpace()->findOrCreateBPPoint(flowGraph->getFunction(),
@@ -505,7 +482,6 @@ BPatch_Vector<BPatch_point*> *BPatch_basicBlock::findPoint(bool(*filter)(Instruc
   return findPointByPredicate(filterPtr);
 }
 
-// returns BPatch_point for an instPoint, unless the point isn't in this block
 BPatch_point *BPatch_basicBlock::convertPoint(instPoint *pt)
 {
   BPatch_point *bpPt = NULL;
@@ -518,8 +494,6 @@ BPatch_point *BPatch_basicBlock::convertPoint(instPoint *pt)
   return bpPt;
 }
 
-// does not return duplicates even if some points belong to multiple categories
-//
 void BPatch_basicBlock::getAllPoints(std::vector<BPatch_point*>& bpPoints)
 {
   instPoint *entry = instPoint::blockEntry(ifunc(), iblock);
@@ -542,14 +516,6 @@ BPatch_function * BPatch_basicBlock::getCallTarget()
   return flowGraph->addSpace->findOrCreateBPFunc(callee, NULL);
 }
 
-
-/*
- * BPatch_basicBlock::getInstructions
- *
- * Returns a vector of the instructions contained within this block
- *
- */
-
 bool BPatch_basicBlock::getInstructions(std::vector<InstructionAPI::Instruction>& insns) {
   using namespace InstructionAPI;
 

dyninstAPI/src/BPatch_basicBlockLoop.C

@@ -43,8 +43,6 @@
 #include "block.h"
 using namespace std;
 using namespace Dyninst::PatchAPI;
-//constructors
-//internal use only
 
 BPatch_basicBlockLoop::BPatch_basicBlockLoop(BPatch_flowGraph *fg, PatchLoop* loop) 
     : flowGraph(fg), parent(NULL) 
@@ -110,7 +108,6 @@ int BPatch_basicBlockLoop::getBackEdges(BPatch_Vector<BPatch_edge*> &edges)
    return edges.size();
 }
 
-// this is a private function, invoked by BPatch_flowGraph::createLoops
 void BPatch_basicBlockLoop::addBackEdges
 (std::vector< BPatch_edge*> &newEdges)
 {
@@ -137,30 +134,24 @@ BPatch_basicBlockLoop::getLoops(BPatch_Vector<BPatch_basicBlockLoop*>& nls,
    return true;
 }
 
-//method that returns the nested loops inside the loop. It returns a set
-//of basicBlockLoop that are contained. It might be useful to add nest 
-//as a field of this class but it seems it is not necessary at this point
 bool
 BPatch_basicBlockLoop::getContainedLoops(BPatch_Vector<BPatch_basicBlockLoop*>& nls)
 {
   return getLoops(nls, false);
 }
 
-// get the outermost loops nested under this loop
 bool 
 BPatch_basicBlockLoop::getOuterLoops(BPatch_Vector<BPatch_basicBlockLoop*>& nls)
 {
   return getLoops(nls, true);
 }
 
-//returns the basic blocks in the loop
 bool BPatch_basicBlockLoop::getLoopBasicBlocks(BPatch_Vector<BPatch_basicBlock*>& bbs) {
    bbs.insert(bbs.end(), basicBlocks.begin(), basicBlocks.end());
   return true;
 }
 
 
-// returns the basic blocks in this loop, not those of its inner loops
 bool BPatch_basicBlockLoop::getLoopBasicBlocksExclusive(BPatch_Vector<BPatch_basicBlock*>& bbs) {
     // start with a copy of all this loops basic blocks
    std::set<BPatch_basicBlock*> allBlocks(basicBlocks);