Add patchAPI/AddrSpace.h

docs/patchAPI/developer/API.rst

@@ -8,4 +8,5 @@ PatchAPI
   :hidden:
   :maxdepth: 1
 
+  AddrSpace.h
   ParseCallback.h

docs/patchAPI/developer/AddrSpace.h.rst

@@ -0,0 +1,16 @@
+.. _`sec-dev:AddrSpace.h`:
+
+AddrSpace.h
+###########
+
+.. cpp:namespace:: Dyninst::PatchAPI::dev
+
+.. cpp:class:: AddrSpace
+
+  .. cpp:function:: protected bool init(Dyninst::PatchAPI::PatchObject*)
+  .. cpp:function:: protected AddrSpace()
+  .. cpp:function:: protected explicit AddrSpace(Dyninst::PatchAPI::AddrSpace*)
+
+  .. cpp:member:: protected Dyninst::PatchAPI::ObjMap obj_map_
+  .. cpp:member:: protected Dyninst::PatchAPI::PatchObject* first_object_
+  .. cpp:member:: protected Dyninst::PatchAPI::PatchMgrPtr mgr_

docs/patchAPI/public/AddrSpace.h.rst

@@ -1,95 +1,102 @@
+.. _`sec:AddrSpace.h`:
+
 AddrSpace.h
-===========
+###########
+
+.. cpp:namespace:: Dyninst::PatchAPI
+
+.. cpp:class:: AddrSpace
+
+  **The address space of a Mutatee**
+
+  Contains a collection of :cpp:class::`PatchObject`\ s that represent shared
+  libraries or a binary executable. Programmers implement
+  some memory management interfaces in the AddrSpace class to determine
+  the type of the code patching - 1st party, 3rd party, or binary
+  rewriting.
+
+  .. cpp:type:: std::map<const CodeObject*, PatchObject*> ObjMap
+
+  .. cpp:function:: virtual bool write(PatchObject* obj, Address to, Address from, size_t size)
+
+      Copies ``size`` bytes from the source address ``from`` in the
+      mutator to the destination address ``to`` in the mutatee.
+
+      If the instrumentation is for binary rewriting, the source address is the relative offset
+      for ``obj``. Otherwise, it's an absolute address.
+
+      Returns ``false`` on error.
+
+  .. cpp:function:: virtual Address malloc(PatchObject* obj, size_t size, Address near)
+
+      Allocates a buffer of ``size`` bytes in the mutatee.
+
+      The address ``near`` is a relative address in the object ``obj``, if the
+      instrumentation is for binary rewriting; otherwise, ``near`` is an
+      absolute address, where this method tries to allocate a buffer near the
+      address ``near``.
+
+      Returns 0 on failure.
+
+  .. cpp:function:: virtual Address realloc(PatchObject* obj, Address orig, size_t size)
+
+      Reallocates a buffer of ``size`` bytes in the mutatee.
+
+      The original buffer is at the address ``orig``. This method tries to
+      reallocate the buffer near the address ``orig``, where ``orig`` is a
+      relative address in the PatchObject. If the instrumentation is for binary
+      rewriting, the source address is the relative offset for ``obj``. Otherwise,
+      it's an absolute address.
+
+      Returns 0 on failure.
 
-.. cpp:namespace:: Dyninst::patchAPI
+  .. cpp:function:: virtual bool free(PatchObject* obj, Address orig)
 
-AddrSpace
-=========
+      Deallocates a buffer in the mutatee at the address ``orig``.
 
-**Declared in**: AddrSpace.h
+      If the instrumentation is for binary rewriting, the source address is the relative
+      offset for ``obj``. Otherwise, it's an absolute address.
 
-The AddrSpace class represents the address space of a **Mutatee**, where
-it contains a collection of **PatchObjects** that represent shared
-libraries or a binary executable. In addition, programmers implement
-some memory management interfaces in the AddrSpace class to determine
-the type of the code patching - 1st party, 3rd party, or binary
-rewriting.
+      If this method succeeds, it returns true; otherwise, it returns false.
 
-.. code-block:: cpp
-    
-    virtual bool write(PatchObject* obj, Address to, Address from, size_t size);
+  .. cpp:function:: virtual bool loadObject(PatchObject* obj)
 
-This method copies *size*-byte data stored at the address *from* on the
-**Mutator** side to the address *to* on the **Mutatee** side. The
-parameter *to* is the relative offset for the PatchObject *obj*, if the
-instrumentation is for binary rewriting; otherwise *to* is an absolute
-address.
+      Loads ``obj`` into the address space.
 
-If the write operation succeeds, this method returns true; otherwise,
-false.
+      Returns ``false`` on error.
 
-.. code-block:: cpp
-    
-    virtual Address malloc(PatchObject* obj, size_t size, Address near);
+  .. cpp:type:: ObjMap& objMap()
 
-This method allocates a buffer of *size* bytes on the **Mutatee** side.
-The address *near* is a relative address in the object *obj*, if the
-instrumentation is for binary rewriting; otherwise, *near* is an
-absolute address, where this method tries to allocate a buffer near the
-address *near*.
+      Returns a mapping from code objects to patch objects.
 
-If this method succeeds, it returns a non-zero address; otherwise, it
-returns 0.
+      The ``PatchObject``\ s in all mappings represent all binary objects (either
+      executable or libraries loaded) in this address space.
 
-.. code-block:: cpp
-    
-    virtual Address realloc(PatchObject* obj, Address orig, size_t size);
+  .. cpp:function:: PatchObject* findObject(const ParseAPI::CodeObject* obj) const
 
-This method reallocates a buffer of *size* bytes on the **Mutatee**
-side. The original buffer is at the address *orig*. This method tries to
-reallocate the buffer near the address *orig*, where *orig* is a
-relative address in the PatchObject *obj* if the instrumentation is for
-binary rewriting; otherwise, *orig* is an absolute address.
+      Find the patch corresponding to ``obj`` in the address space.
 
-If this method succeeds, it returns a non-zero address; otherwise, it
-returns 0.
+      Returns ``NULL`` if ``obj`` does not correspond to any patch.
 
-.. code-block:: cpp
-    
-    virtual bool free(PatchObject* obj, Address orig);
+  .. cpp:function:: template <class Iter> void objs(Iter iter)
 
-This method deallocates a buffer on the **Mutatee** side at the address
-*orig*. If the instrumentation is for binary rewriting, then the
-parameter *orig* is a relative address in the object *obj*; otherwise,
-*orig* is an absolute address.
+      Writes all of the patch objects into ``iter``.
 
-If this method succeeds, it returns true; otherwise, it returns false.
+      ``Iter`` must be at least a C++ `LegacyForwardIterator <https://en.cppreference.com/w/cpp/named_req/ForwardIterator>`_.
 
-.. code-block:: cpp
-    
-    virtual bool loadObject(PatchObject* obj);
+  .. cpp:function:: PatchObject* executable()
 
-This method loads a PatchObject into the address space. If this method
-succeeds, it returns true; otherwise, it returns false.
+      Returns the PatchObject of the executable of the mutatee.
 
-.. code-block:: cpp
-    
-    typedef std::map<const ParseAPI::CodeObject*, PatchObject*> AddrSpace::ObjMap;
-    ObjMap& objMap();
+  .. cpp:function:: PatchMgrPtr mgr()
 
-Returns a set of mappings from ParseAPI::CodeObjects to PatchObjects,
-where PatchObjects in all mappings represent all binary objects (either
-executable or libraries loaded) in this address space.
+      Returns the PatchMgr’s pointer, where the PatchMgr contains this address
+      space.
 
-.. code-block:: cpp
-    
-    PatchObject* executable();
+  .. cpp:function:: std::string format() const
 
-Returns the PatchObject of the executable of the **Mutatee**.
+      Returns a string representation of the starting address of the address space.
 
-.. code-block:: cpp
-    
-    PatchMgrPtr mgr();
+  .. cpp:function:: bool consistency(const PatchMgr *mgr) const
 
-Returns the PatchMgr’s pointer, where the PatchMgr contains this address
-space.
+      Checks if all contained patches are managed by ``mgr``.

patchAPI/h/AddrSpace.h

@@ -28,8 +28,6 @@
  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
  */
 
-/* Plugin Interface */
-
 #ifndef PATCHAPI_H_ADDRSPACE_H_
 #define PATCHAPI_H_ADDRSPACE_H_
 
@@ -42,9 +40,6 @@
 namespace Dyninst {
 namespace PatchAPI {
 
-/* Interface specification for the interation between a PatchMgr and
-   the address space */
-
 class PATCHAPI_EXPORT AddrSpace {
     friend class PatchMgr;
     friend class PatchFunction;
@@ -53,11 +48,9 @@ class PATCHAPI_EXPORT AddrSpace {
     static AddrSpace* create(PatchObject* obj);
     virtual ~AddrSpace();
 
-    // Write data in mutatee's address space
     virtual bool write(PatchObject* /*obj*/, Dyninst::Address /*to*/,
                                        Dyninst::Address /*from*/, size_t /*size*/);
 
-    // Memory allocation / reallocation / deallocation in mutatee's addressSpace
     virtual Dyninst::Address malloc(PatchObject* /*obj*/, size_t /*size*/,
                                            Dyninst::Address /*near*/);
 
@@ -66,14 +59,12 @@ class PATCHAPI_EXPORT AddrSpace {
 
     virtual bool free(PatchObject* /*obj*/, Dyninst::Address /*orig*/);
 
-    // Load a binary oject into the address space
     virtual bool loadObject(PatchObject* obj);
 
-    // Getters
     typedef std::map<const ParseAPI::CodeObject*, PatchObject*> ObjMap;
     ObjMap& objMap() { return obj_map_; }
     PatchObject* findObject(const ParseAPI::CodeObject*) const;
-    template <class Iter> void objs(Iter iter); // EXPORTED
+    template <class Iter> void objs(Iter iter);
     PatchObject* executable() { return first_object_; }
     PatchMgrPtr mgr() const { return mgr_; }