Changeset 19757 in vbox for trunk/include/iprt

Timestamp:

May 15, 2009 11:37:31 PM (16 years ago)

Author:

vboxsync

Message:

VMM,IPRT,DBGC: Debug address spaces.

File:

• trunk/include/iprt/dbg.h (modified) (9 diffs)

trunk/include/iprt/dbg.h

@@ -42 +42 @@
 /** NIL debug segment index. */
 #define NIL_RTDBGSEGIDX     UINT32_C(0xffffffff)
+/** The last normal segment index. */
+#define RTDBGSEGIDX_LAST    UINT32_C(0xffffffef)
 /** Special segment index that indicates that the offset is a relative
  * virtual address (RVA). I.e. an offset from the start of the module. */
@@ -144 +146 @@
 
 /**
- * Destroys the address space.
- *
- * This means unlinking all the modules it currently contains, potentially
+ * Retains a reference to the address space.
+ *
+ * @returns New reference count, UINT32_MAX on invalid handle (asserted).
+ *
+ * @param   hDbgAs          The address space handle.
+ *
+ * @remarks Will not take any locks.
+ */
+RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
+
+/**
+ * Release a reference to the address space.
+ *
+ * When the reference count reaches zero, the address space is destroyed.
+ * That means unlinking all the modules it currently contains, potentially
  * causing some or all of them to be destroyed as they are managed by
  * reference counting.
  *
- * @returns IPRT status code.
- *
- * @param   hDbgAs          The address space handle. A NIL handle will
- *                          be quietly ignored.
- */
-RTDECL(int) RTDbgAsDestroy(RTDBGAS hDbgAs);
+ * @returns New reference count, UINT32_MAX on invalid handle (asserted).
+ *
+ * @param   hDbgAs          The address space handle. The NIL handle is quietly
+ *                          ignored and 0 is returned.
+ *
+ * @remarks Will not take any locks.
+ */
+RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
 
 /**
@@ -164 +180 @@
  *
  * @param   hDbgAs          The address space handle.
+ *
+ * @remarks Will not take any locks.
  */
 RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
@@ -174 +192 @@
  *
  * @param   hDbgAs          The address space handle.
+ *
+ * @remarks Will not take any locks.
  */
 RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
@@ -184 +204 @@
  *
  * @param   hDbgAs          The address space handle.
+ *
+ * @remarks Will not take any locks.
  */
 RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
@@ -196 +218 @@
  *
  * @param   hDbgAs          The address space handle.
+ *
+ * @remarks Will not take any locks.
  */
 RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
+
+/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
+ * @{ */
+/** Replace all conflicting module.
+ * (The conflicting modules will be removed the address space and their
+ * references released.) */
+#define RTDBGASLINK_FLAGS_REPLACE       RT_BIT_32(0)
+/** Mask containing the valid flags. */
+#define RTDBGASLINK_FLAGS_VALID_MASK    UINT32_C(0x00000001)
+/** @} */
 
 /**
@@ -212 +246 @@
  * @param   hDbgMod         The module handle of the module to be linked in.
  * @param   ImageAddr       The address to link the module at.
- */
-RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr);
+ * @param   fFlags          See RTDBGASLINK_FLAGS_*.
+ */
+RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
 
 /**
@@ -230 +265 @@
  *                          linked in.
  * @param   SegAddr         The address to link the segment at.
- */
-RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr);
+ * @param   fFlags          See RTDBGASLINK_FLAGS_*.
+ */
+RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
 
 /**
@@ -414 +450 @@
  * @{
  */
-RTDECL(int)         RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, const char *pszImgFile, const char *pszDbgFile);
-RTDECL(int)         RTDbgModDestroy(RTDBGMOD hDbgMod);
+RTDECL(int)         RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cb, uint32_t fFlags);
+RTDECL(int)         RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t fFlags);
+RTDECL(int)         RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTUINTPTR uSubtrahend, uint32_t fFlags);
 RTDECL(uint32_t)    RTDbgModRetain(RTDBGMOD hDbgMod);
 RTDECL(uint32_t)    RTDbgModRelease(RTDBGMOD hDbgMod);