Changeset 3541 for trunk/kStuff/include/k/kDbg.h

Timestamp:

Aug 25, 2007, 5:46:14 AM (18 years ago)

Author:

bird

Message:

errors and stuff.

File:

• trunk/kStuff/include/k/kDbg.h (modified) (8 diffs)

trunk/kStuff/include/k/kDbg.h

@@ -41 +41 @@
 /** The max symbol name length used by the debug reader. */
 #define KDBG_SYMBOL_MAX     384
-
-/** @name   kDbg Status codes
- * (Success is indicated by the value 0.)
- * @{ */
-#define KDBG_ERR_BASE                                   430000
-
-/** An API was given an invalid parameter. */
-#define KDBG_ERR_INVALID_PARAMETER                      (KDBG_ERR_BASE + 0)
-/** A pointer argument is not valid. */
-#define KDBG_ERR_INVALID_POINTER                        (KDBG_ERR_BASE + 1)
-/** A handle argument is not valid. */
-#define KDBG_ERR_INVALID_HANDLE                         (KDBG_ERR_BASE + 2)
-/** A parameter is out of range. */
-#define KDBG_ERR_OUT_OF_RANGE                           (KDBG_ERR_BASE + 3)
-/** Out of memory. */
-#define KDBG_ERR_NO_MEMORY                              (KDBG_ERR_BASE + 4)
-/** The specified file was not found. */
-#define KDBG_ERR_FILE_NOT_FOUND                         (KDBG_ERR_BASE + 5)
-/** Hit some unimplemented functionality - feel free to implement it :-) . */
-#define KDBG_ERR_NOT_IMPLEMENTED                        (KDBG_ERR_BASE + 6)
-/** Generic error. */
-#define KDBG_ERR_GENERAL_FAILURE                        (KDBG_ERR_BASE + 9)
-
-/** The (module) format isn't known to use. */
-#define KDBG_ERR_UNKOWN_FORMAT                          (KDBG_ERR_BASE + 10)
-/** The (module) format isn't supported by this kDbg build. */
-#define KDBG_ERR_FORMAT_NOT_SUPPORTED                   (KDBG_ERR_BASE + 11)
-/** A specified address or an address found in the debug info is invalid. */
-#define KDBG_ERR_INVALID_ADDRESS                        (KDBG_ERR_BASE + 12)
-/** The dbghelp.dll is too old or something like that. */
-#define KDBG_ERR_DBGHLP_VERSION_MISMATCH                (KDBG_ERR_BASE + 13)
-/** Invalid executable format. */
-#define KDBG_ERR_BAD_EXE_FORMAT                         (KDBG_ERR_BASE + 14)
-
-/** @} */
-
 
 /** @name   Special Segments
@@ -131 +95 @@
  *
  * @returns VINF_SUCCESS on success.
- * @returns KDBG_ERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in.
+ * @returns KERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in.
  *
  * @param   pLine       The line number to be freed.
@@ -199 +163 @@
  *
  * @returns VINF_SUCCESS on success.
- * @returns KDBG_ERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in.
+ * @returns KERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in.
  *
  * @param   pSymbol     The symbol to be freed.
@@ -206 +170 @@
 
 
+/** Pointer to a kDbgHlp file structure (abstract). */
+typedef struct KDBGHLPFILE *PKDBGHLPFILE;
 
 /** A debug module handle. */
 typedef struct KDBGMOD *PKDBGMOD;
+
+/**
+ * The debug module method table.
+ */
+typedef struct KDBGMODOPS
+{
+    /** The name of the reader. */
+    const char *pszName;
+
+    /** Pointer to the next debug module readers.
+     * This is only used for dynamically registered readers. */
+    struct KDBGMODOPS  *pNext;
+
+    /**
+     * Tries to open the module.
+     *
+     * @returns 0 on success, KDBG_ERR on failure.
+     * @param   pFile           The file
+     * @param   ppMod           Where to store the module that's been opened.
+     * @param   off             The file offset of the debug info. This is 0 if there isn't
+     *                          any specfic debug info section and the reader should start
+     *                          looking for debug info at the start of the file.
+     * @param   cb              The size of the debug info in the file. INT64_MAX if we don't
+     *                          know or there isn't any particular debug info section in the file.
+     * @param   pLdrMod         The associated loader module. This can be NULL.
+     *
+     * @remark  This is NULL for the builtin readers.
+     */
+    int (*pfnOpen)(PKDBGMOD *ppMod, PKDBGHLPFILE pFile, KFOFF off, KFOFF cb, struct KLDRMOD *pLdrMod);
+
+    /**
+     * Closes the module.
+     *
+     * This should free all resources associated with the module
+     * except the pMod which is freed by the caller.
+     *
+     * @returns IPRT status code.
+     * @param   pMod        The module.
+     */
+    int (*pfnClose)(PKDBGMOD pMod);
+
+    /**
+     * Gets a symbol by segment:offset.
+     * This will be approximated to the nearest symbol if there is no exact match.
+     *
+     * @returns 0 on success. KLDR_ERR_* on failure.
+     * @param   pMod        The module.
+     * @param   iSegment    The segment this offset is relative to.
+     *                      The -1 segment is special, it means that the addres is relative to
+     *                      the image base. The image base is where the first bit of the image
+     *                      is mapped during load.
+     * @param   off         The offset into the segment.
+     * @param   pSym        Where to store the symbol details.
+     */
+    int (*pfnQuerySymbol)(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PKDBGSYMBOL pSym);
+
+    /**
+     * Gets a line number entry by segment:offset.
+     * This will be approximated to the nearest line number there is no exact match.
+     *
+     * @returns 0 on success. KLDR_ERR_* on failure.
+     * @param   pMod        The module.
+     * @param   iSegment    The segment this offset is relative to.
+     *                      The -1 segment is special, it means that the addres is relative to
+     *                      the image base. The image base is where the first bit of the image
+     *                      is mapped during load.
+     * @param   off         The offset into the segment.
+     * @param   pLine       Where to store the line number details.
+     */
+    int (*pfnQueryLine)(PKDBGMOD pMod, KI32 iSegment, KDBGADDR uOffset, PKDBGLINE pLine);
+
+    /** This is just to make sure you've initialized all the fields.
+     * Must be identical to pszName. */
+    const char *pszName2;
+} KDBGMODOPS;
+/** Pointer to a module method table. */
+typedef KDBGMODOPS *PKDBGMODOPS;
+/** Pointer to a const module method table. */
+typedef const KDBGMODOPS *PCKDBGMODOPS;
+
+/**
+ * Register a debug module reader with the kDbgModule component.
+ *
+ * Dynamically registered readers are kept in FIFO order, and external
+ * readers will be tried after the builtin ones.
+ *
+ * @returns 0 on success.
+ * @returns KERR_INVALID_POINTER if pOps is missing bits.
+ * @returns KERR_INVALID_PARAMETER if pOps is already in the list.
+ * @param   pOps        The reader method table, kDbg takes owner ship of
+ *                      this. This must be writeable as the pNext pointer
+ *                      will be update. It must also stick around for as
+ *                      long as kDbg is in use.
+ */
+KDBG_DECL(int) kDbgModuleRegisterReader(PKDBGMODOPS pOps)
+;
+
+
+
+/**
+ * Internal representation of a debug module.
+ */
+typedef struct KDBGMOD
+{
+    /** Magic value (KDBGMOD_MAGIC). */
+    KI32            u32Magic;
+    /** The handle to the module. (If closed, this is NIL_RTFILE.) */
+    PKDBGHLPFILE    pFile;
+    /** Pointer to the method table. */
+    PCKDBGMODOPS    pOps;
+} KDBGMOD;
+
+
+/** The magic value for the debug module structure. (Some dead english writer) */
+#define KDBGMOD_MAGIC      0x19200501
+/** The magic value of a dead module structure. */
+#define KDBGMOD_MAGIC_DEAD 0x19991231
+
 
 /**
@@ -240 +324 @@
  * @param   pSym        Where to store the symbol details.
  */
-KDBG_DECL(int) kDbgModuleQuerySymbol(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PKDBGSYMBOL pSym);
+KDBG_DECL(int) kDbgModuleQuerySymbol(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PKDBGSYMBOL pSym);
 
 /**
@@ -256 +340 @@
  *                      Free the returned symbol using kDbgSymbolFree().
  */
-KDBG_DECL(int) kDbgModuleQuerySymbolA(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PPKDBGSYMBOL ppSym);
+KDBG_DECL(int) kDbgModuleQuerySymbolA(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PPKDBGSYMBOL ppSym);
 
 /**
@@ -271 +355 @@
  * @param   pLine       Where to store the line number details.
  */
-KDBG_DECL(int) kDbgModuleQueryLine(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PKDBGLINE pLine);
+KDBG_DECL(int) kDbgModuleQueryLine(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PKDBGLINE pLine);
 
 /**
@@ -287 +371 @@
  *                      Free the returned line number using kDbgLineFree().
  */
-KDBG_DECL(int) kDbgModuleQueryLineA(PKDBGMOD pMod, int32_t iSegment, KDBGADDR off, PPKDBGLINE ppLine);
+KDBG_DECL(int) kDbgModuleQueryLineA(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PPKDBGLINE ppLine);