Add dyninstAPI/BPatch_frame.h

docs/dyninstAPI/developer/API.rst

@@ -19,6 +19,7 @@ DyninstAPI
   BPatch_collections.h
   BPatch_dll.h
   BPatch_flowGraph.h
+  BPatch_frame.h
   BPatch_libInfo.h
   BPatch_memoryAccessAdapter.h
   BPatch_private.h
@@ -77,4 +78,4 @@ DyninstAPI
   syscalltrap.h
   trapMappings.h
   unix.h
-  util.h
+  util.h

docs/dyninstAPI/developer/BPatch_frame.h.rst

@@ -0,0 +1,16 @@
+.. _`sec-dev:BPatch_frame.h`:
+
+BPatch_frame.h
+##############
+
+.. cpp:namespace:: dev
+
+.. cpp:class:: BPatch_frame
+
+  .. cpp:member:: private bool isSynthFrame
+
+    BPatch defines that a trampoline is effectively a "function call" and puts an extra tramp on the stack. Various people (frex, Paradyn) really don't want to see this frame. To make life simpler for everyone, we add a "only call if you know what you're doing" flag.
+
+  .. cpp:member:: private BPatch_point *point_
+
+    This is _so_ much easier than looking it up later. If we're in instrumentation, stash the point

docs/dyninstAPI/public/BPatch_frame.h.rst

@@ -5,50 +5,59 @@ BPatch_frame.h
 
 .. cpp:class:: BPatch_frame
    
-  A **BPatch_frame** object represents a stack frame. The getCallStack
-  member function of BPatch_thread returns a vector of BPatch_frame
-  objects representing the frames currently on the stack.
+  **Frame information needed for stack walking**
 
+  .. cpp:function:: BPatch_frame(BPatch_thread *_thread, void *_pc, void *_fp, bool isf = false, \
+                                 bool istr = false, BPatch_point *point = NULL, bool isSynth = false)
+
+  .. cpp:function:: BPatch_frame()
   .. cpp:function:: BPatch_frameType getFrameType()
 
-    Return the type of the stack frame. Possible types are:
+    Returns the type of the stack frame.
+
+  .. cpp:function:: bool isSynthesized()
+
+    Returns true if this frame was artificially created, false otherwise.
 
-    +------------------------+------------------------------------+
-    | **Frame Type**         | **Meaning**                        |
-    +------------------------+------------------------------------+
-    | BPatch_frameNormal     | A normal stack frame.              |
-    +------------------------+------------------------------------+
-    | BPatch_frameSignal     | A frame that represents a signal   |
-    |                        | invocation.                        |
-    +------------------------+------------------------------------+
-    | BPatch_frameTrampoline | A frame the represents a call into |
-    |                        | instrumentation code.              |
-    +------------------------+------------------------------------+
+    Per-frame method for determining  how the frame was created.
 
-  .. cpp:function:: void *getFP()
+    .. warning:: Only call if you know what you are doing!
 
-    Return the frame pointer for the stack frame.
+  .. cpp:function:: BPatch_thread * getThread()
+
+    Returns the thread associated with the stack frame.
+
+  .. cpp:function:: BPatch_point * getPoint()
+
+    For stack frames corresponding to inserted instrumentation, returns the
+    instrumentation point where that instrumentation was inserted. For other
+    frames, returns NULL.
 
   .. cpp:function:: void *getPC()
 
     Returns the program counter associated with the stack frame.
 
-  .. cpp:function:: BPatch_function *findFunction()
+  .. cpp:function:: void * getFP()
 
-    Returns the function associated with the stack frame.
+    Return the frame pointer for the stack frame.
 
-  .. cpp:function:: BPatch_thread *getThread()
+  .. cpp:function:: BPatch_function * findFunction()
 
-    Returns the thread associated with the stack frame.
+    Returns the function corresponding to this stack frame, NULL if there is none
 
-  .. cpp:function:: BPatch_point *getPoint()
+  .. cpp:function:: BPatch_point * findPoint()
 
-  .. cpp:function:: BPatch_point *findPoint()
 
-    For stack frames corresponding to inserted instrumentation, returns the
-    instrumentation point where that instrumentation was inserted. For other
-    frames, returns NULL.
+.. cpp:enum:: BPatch_frameType
 
-  .. cpp:function:: bool isSynthesized()
+  .. cpp:enumerator:: BPatch_frameNormal
 
-    Returns true if this frame was artificially created, false otherwise.
+    for a stack frame for a function
+
+  .. cpp:enumerator:: BPatch_frameSignal
+
+    for the stack frame created when a signal is delivered
+
+  .. cpp:enumerator:: BPatch_frameTrampoline
+
+    for a stack frame created by internal Dyninst instrumentation

dyninstAPI/h/BPatch_frame.h

@@ -33,9 +33,6 @@
 
 #include "BPatch_Vector.h"
 
-/*
- * Frame information needed for stack walking
- */
 typedef enum {
     BPatch_frameNormal,
     BPatch_frameSignal,
@@ -53,14 +50,8 @@ class BPATCH_DLL_EXPORT BPatch_frame {
     void *fp;
     bool isSignalFrame;
     bool isTrampFrame;
-    // BPatch defines that a trampoline is effectively a "function call" and
-    // puts an extra tramp on the stack. Various people (frex, Paradyn) really
-    // don't want to see this frame. To make life simpler for everyone, we
-    // add a "only call if you know what you're doing" flag.
     bool isSynthFrame;
 
-    // This is _so_ much easier than looking it up later. If we're
-    // in instrumentation, stash the point
     BPatch_point *point_;
 
 public:
@@ -72,43 +63,20 @@ class BPATCH_DLL_EXPORT BPatch_frame {
                  bool isSynth = false);
 
 
-    //  BPatch_frame::getFrameType
-    //  Returns type of frame: BPatch_frameNormal for a stack frame for a 
-    //  function, BPatch_frameSignal for the stack frame created when a signal 
-    //  is delivered, or BPatch_frameTrampoline for a stack frame created by 
-    //  internal Dyninst instrumentation.
     BPatch_frameType getFrameType();
 
-    //  Only call if you know what you are doing; per-frame method for determining
-    //  how the frame was created.
     bool isSynthesized();
 
-    //  BPatch_frame::getThread
-    //  Returns:  value of program counter
-
     BPatch_thread * getThread(); 
 
-    //  BPatch_frame::getThread
-    //  Returns:  value of program counter
-
     BPatch_point * getPoint(); 
 
-    //  BPatch_frame::getPC
-    //  Returns:  value of program counter
-
     void * getPC(); 
 
-    //  BPatch_frame::getFP
-
     void * getFP(); 
 
-    //  BPatch_frame::findFunction
-    //  Returns:  the function corresponding to this stack frame, NULL 
-    //   if there is none
-
     BPatch_function * findFunction();
-
-    // The following are planned but no yet implemented:
+
     // int getSignalNumber();
 
     BPatch_point * findPoint();