/* $Id: dbg.h 98103 2023-01-17 14:15:46Z vboxsync $ */ /** @file * IPRT - Debugging Routines. */ /* * Copyright (C) 2008-2023 Oracle and/or its affiliates. * * This file is part of VirtualBox base platform packages, as * available from https://www.virtualbox.org. * * This program is free software; you can redistribute it and/or * modify it under the terms of the GNU General Public License * as published by the Free Software Foundation, in version 3 of the * License. * * This program is distributed in the hope that it will be useful, but * WITHOUT ANY WARRANTY; without even the implied warranty of * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU * General Public License for more details. * * You should have received a copy of the GNU General Public License * along with this program; if not, see . * * The contents of this file may alternatively be used under the terms * of the Common Development and Distribution License Version 1.0 * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included * in the VirtualBox distribution, in which case the provisions of the * CDDL are applicable instead of those of the GPL. * * You may elect to license modified versions of this file under the * terms and conditions of either the GPL or the CDDL or both. * * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0 */ #ifndef IPRT_INCLUDED_dbg_h #define IPRT_INCLUDED_dbg_h #ifndef RT_WITHOUT_PRAGMA_ONCE # pragma once #endif #include #include #include RT_C_DECLS_BEGIN /** @defgroup grp_rt_dbg RTDbg - Debugging Routines * @ingroup grp_rt * @{ */ /** Debug segment index. */ typedef uint32_t RTDBGSEGIDX; /** Pointer to a debug segment index. */ typedef RTDBGSEGIDX *PRTDBGSEGIDX; /** Pointer to a const debug segment index. */ typedef RTDBGSEGIDX const *PCRTDBGSEGIDX; /** 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. */ #define RTDBGSEGIDX_RVA UINT32_C(0xfffffff0) /** Special segment index that indicates that the offset is a absolute. */ #define RTDBGSEGIDX_ABS UINT32_C(0xfffffff1) /** The last valid special segment index. */ #define RTDBGSEGIDX_SPECIAL_LAST RTDBGSEGIDX_ABS /** The last valid special segment index. */ #define RTDBGSEGIDX_SPECIAL_FIRST (RTDBGSEGIDX_LAST + 1U) /** @name RTDBGSYMADDR_FLAGS_XXX * Flags used when looking up a symbol by address. * @{ */ /** Less or equal address. (default) */ #define RTDBGSYMADDR_FLAGS_LESS_OR_EQUAL UINT32_C(0) /** Greater or equal address. */ #define RTDBGSYMADDR_FLAGS_GREATER_OR_EQUAL UINT32_C(1) /** Don't consider absolute symbols in deferred modules. */ #define RTDBGSYMADDR_FLAGS_SKIP_ABS_IN_DEFERRED UINT32_C(2) /** Don't search for absolute symbols if it's expensive. */ #define RTDBGSYMADDR_FLAGS_SKIP_ABS UINT32_C(4) /** Mask of valid flags. */ #define RTDBGSYMADDR_FLAGS_VALID_MASK UINT32_C(7) /** @} */ /** @name RTDBGSYMBOLADD_F_XXX - Flags for RTDbgModSymbolAdd and RTDbgAsSymbolAdd. * @{ */ /** Replace existing symbol with same address. */ #define RTDBGSYMBOLADD_F_REPLACE_SAME_ADDR UINT32_C(0x00000001) /** Replace any existing symbols overlapping the symbol range. */ #define RTDBGSYMBOLADD_F_REPLACE_ANY UINT32_C(0x00000002) /** Adjust sizes on address conflict. This applies to the symbol being added * as well as existing symbols. */ #define RTDBGSYMBOLADD_F_ADJUST_SIZES_ON_CONFLICT UINT32_C(0x00000004) /** Mask of valid flags. */ #define RTDBGSYMBOLADD_F_VALID_MASK UINT32_C(0x00000007) /** @} */ /** Max length (including '\\0') of a segment name. */ #define RTDBG_SEGMENT_NAME_LENGTH (128 - 8 - 8 - 8 - 4 - 4) /** * Debug module segment. */ typedef struct RTDBGSEGMENT { /** The load address. * RTUINTPTR_MAX if not applicable. */ RTUINTPTR Address; /** The image relative virtual address of the segment. * RTUINTPTR_MAX if not applicable. */ RTUINTPTR uRva; /** The segment size. */ RTUINTPTR cb; /** The segment flags. (reserved) */ uint32_t fFlags; /** The segment index. */ RTDBGSEGIDX iSeg; /** Symbol name. */ char szName[RTDBG_SEGMENT_NAME_LENGTH]; } RTDBGSEGMENT; /** Pointer to a debug module segment. */ typedef RTDBGSEGMENT *PRTDBGSEGMENT; /** Pointer to a const debug module segment. */ typedef RTDBGSEGMENT const *PCRTDBGSEGMENT; /** * Return type. */ typedef enum RTDBGRETURNTYPE { /** The usual invalid 0 value. */ RTDBGRETURNTYPE_INVALID = 0, /** Near 16-bit return. */ RTDBGRETURNTYPE_NEAR16, /** Near 32-bit return. */ RTDBGRETURNTYPE_NEAR32, /** Near 64-bit return. */ RTDBGRETURNTYPE_NEAR64, /** Far 16:16 return. */ RTDBGRETURNTYPE_FAR16, /** Far 16:32 return. */ RTDBGRETURNTYPE_FAR32, /** Far 16:64 return. */ RTDBGRETURNTYPE_FAR64, /** 16-bit iret return (e.g. real or 286 protect mode). */ RTDBGRETURNTYPE_IRET16, /** 32-bit iret return. */ RTDBGRETURNTYPE_IRET32, /** 32-bit iret return. */ RTDBGRETURNTYPE_IRET32_PRIV, /** 32-bit iret return to V86 mode. */ RTDBGRETURNTYPE_IRET32_V86, /** @todo 64-bit iret return. */ RTDBGRETURNTYPE_IRET64, /** The end of the valid return types. */ RTDBGRETURNTYPE_END, /** The usual 32-bit blowup. */ RTDBGRETURNTYPE_32BIT_HACK = 0x7fffffff } RTDBGRETURNTYPE; /** * Figures the size of the return state on the stack. * * @returns number of bytes. 0 if invalid parameter. * @param enmRetType The type of return. */ DECLINLINE(unsigned) RTDbgReturnTypeSize(RTDBGRETURNTYPE enmRetType) { switch (enmRetType) { case RTDBGRETURNTYPE_NEAR16: return 2; case RTDBGRETURNTYPE_NEAR32: return 4; case RTDBGRETURNTYPE_NEAR64: return 8; case RTDBGRETURNTYPE_FAR16: return 4; case RTDBGRETURNTYPE_FAR32: return 4; case RTDBGRETURNTYPE_FAR64: return 8; case RTDBGRETURNTYPE_IRET16: return 6; case RTDBGRETURNTYPE_IRET32: return 4*3; case RTDBGRETURNTYPE_IRET32_PRIV: return 4*5; case RTDBGRETURNTYPE_IRET32_V86: return 4*9; case RTDBGRETURNTYPE_IRET64: return 5*8; case RTDBGRETURNTYPE_INVALID: case RTDBGRETURNTYPE_END: case RTDBGRETURNTYPE_32BIT_HACK: break; } return 0; } /** * Check if near return. * * @returns true if near, false if far or iret. * @param enmRetType The type of return. */ DECLINLINE(bool) RTDbgReturnTypeIsNear(RTDBGRETURNTYPE enmRetType) { return enmRetType == RTDBGRETURNTYPE_NEAR32 || enmRetType == RTDBGRETURNTYPE_NEAR64 || enmRetType == RTDBGRETURNTYPE_NEAR16; } /** Magic value for RTDBGUNWINDSTATE::u32Magic (James Moody). */ #define RTDBGUNWINDSTATE_MAGIC UINT32_C(0x19250326) /** Magic value for RTDBGUNWINDSTATE::u32Magic after use. */ #define RTDBGUNWINDSTATE_MAGIC_DEAD UINT32_C(0x20101209) /** * Unwind machine state. */ typedef struct RTDBGUNWINDSTATE { /** Structure magic (RTDBGUNWINDSTATE_MAGIC) */ uint32_t u32Magic; /** The state architecture. */ RTLDRARCH enmArch; /** The program counter register. * amd64/x86: RIP/EIP/IP * sparc: PC * arm32: PC / R15 */ uint64_t uPc; /** Return type. */ RTDBGRETURNTYPE enmRetType; /** Register state (see enmArch). */ union { /** RTLDRARCH_AMD64, RTLDRARCH_X86_32 and RTLDRARCH_X86_16. */ struct { /** General purpose registers indexed by X86_GREG_XXX. */ uint64_t auRegs[16]; /** The frame address. */ RTFAR64 FrameAddr; /** Set if we're in real or virtual 8086 mode. */ bool fRealOrV86; /** The flags register. */ uint64_t uRFlags; /** Trap error code. */ uint64_t uErrCd; /** Segment registers (indexed by X86_SREG_XXX). */ uint16_t auSegs[6]; /** Bitmap tracking register we've loaded and which content can possibly be trusted. */ union { /** For effective clearing of the bits. */ uint32_t fAll; /** Detailed view. */ struct { /** Bitmap indicating whether a GPR was loaded (parallel to auRegs). */ uint16_t fRegs; /** Bitmap indicating whether a segment register was loaded (parallel to auSegs). */ uint8_t fSegs; /** Set if uPc was loaded. */ RT_GCC_EXTENSION uint8_t fPc : 1; /** Set if FrameAddr was loaded. */ RT_GCC_EXTENSION uint8_t fFrameAddr : 1; /** Set if uRFlags was loaded. */ RT_GCC_EXTENSION uint8_t fRFlags : 1; /** Set if uErrCd was loaded. */ RT_GCC_EXTENSION uint8_t fErrCd : 1; } s; } Loaded; } x86; /** @todo add ARM and others as needed. */ } u; /** * Stack read callback. * * @returns IPRT status code. * @param pThis Pointer to this structure. * @param uSp The stack pointer address. * @param cbToRead The number of bytes to read. * @param pvDst Where to put the bytes we read. */ DECLCALLBACKMEMBER(int, pfnReadStack,(struct RTDBGUNWINDSTATE *pThis, RTUINTPTR uSp, size_t cbToRead, void *pvDst)); /** User argument (useful for pfnReadStack). */ void *pvUser; } RTDBGUNWINDSTATE; /** * Try read a 16-bit value off the stack. * * @returns pfnReadStack result. * @param pThis The unwind state. * @param uSrcAddr The stack address. * @param puDst The read destination. */ DECLINLINE(int) RTDbgUnwindLoadStackU16(PRTDBGUNWINDSTATE pThis, RTUINTPTR uSrcAddr, uint16_t *puDst) { return pThis->pfnReadStack(pThis, uSrcAddr, sizeof(*puDst), puDst); } /** * Try read a 32-bit value off the stack. * * @returns pfnReadStack result. * @param pThis The unwind state. * @param uSrcAddr The stack address. * @param puDst The read destination. */ DECLINLINE(int) RTDbgUnwindLoadStackU32(PRTDBGUNWINDSTATE pThis, RTUINTPTR uSrcAddr, uint32_t *puDst) { return pThis->pfnReadStack(pThis, uSrcAddr, sizeof(*puDst), puDst); } /** * Try read a 64-bit value off the stack. * * @returns pfnReadStack result. * @param pThis The unwind state. * @param uSrcAddr The stack address. * @param puDst The read destination. */ DECLINLINE(int) RTDbgUnwindLoadStackU64(PRTDBGUNWINDSTATE pThis, RTUINTPTR uSrcAddr, uint64_t *puDst) { return pThis->pfnReadStack(pThis, uSrcAddr, sizeof(*puDst), puDst); } /** Max length (including '\\0') of a symbol name. */ #define RTDBG_SYMBOL_NAME_LENGTH (512 - 8 - 8 - 8 - 4 - 4 - 8) /** * Debug symbol. */ typedef struct RTDBGSYMBOL { /** Symbol value (address). * This depends a bit who you ask. It will be the same as offSeg when you * as RTDbgMod, but the mapping address if you ask RTDbgAs. */ RTUINTPTR Value; /** Symbol size. */ RTUINTPTR cb; /** Offset into the segment specified by iSeg. */ RTUINTPTR offSeg; /** Segment number. */ RTDBGSEGIDX iSeg; /** Symbol Flags. (reserved). */ uint32_t fFlags; /** Symbol ordinal. * This is set to UINT32_MAX if the ordinals aren't supported. */ uint32_t iOrdinal; /** Symbol name. */ char szName[RTDBG_SYMBOL_NAME_LENGTH]; } RTDBGSYMBOL; /** Pointer to debug symbol. */ typedef RTDBGSYMBOL *PRTDBGSYMBOL; /** Pointer to const debug symbol. */ typedef const RTDBGSYMBOL *PCRTDBGSYMBOL; /** * Allocate a new symbol structure. * * @returns Pointer to a new structure on success, NULL on failure. */ RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void); /** * Duplicates a symbol structure. * * @returns Pointer to duplicate on success, NULL on failure. * * @param pSymInfo The symbol info to duplicate. */ RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymInfo); /** * Free a symbol structure previously allocated by a RTDbg method. * * @param pSymInfo The symbol info to free. NULL is ignored. */ RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymInfo); /** Max length (including '\\0') of a debug info file name. */ #define RTDBG_FILE_NAME_LENGTH (260) /** * Debug line number information. */ typedef struct RTDBGLINE { /** Address. * This depends a bit who you ask. It will be the same as offSeg when you * as RTDbgMod, but the mapping address if you ask RTDbgAs. */ RTUINTPTR Address; /** Offset into the segment specified by iSeg. */ RTUINTPTR offSeg; /** Segment number. */ RTDBGSEGIDX iSeg; /** Line number. */ uint32_t uLineNo; /** Symbol ordinal. * This is set to UINT32_MAX if the ordinals aren't supported. */ uint32_t iOrdinal; /** Filename. */ char szFilename[RTDBG_FILE_NAME_LENGTH]; } RTDBGLINE; /** Pointer to debug line number. */ typedef RTDBGLINE *PRTDBGLINE; /** Pointer to const debug line number. */ typedef const RTDBGLINE *PCRTDBGLINE; /** * Allocate a new line number structure. * * @returns Pointer to a new structure on success, NULL on failure. */ RTDECL(PRTDBGLINE) RTDbgLineAlloc(void); /** * Duplicates a line number structure. * * @returns Pointer to duplicate on success, NULL on failure. * * @param pLine The line number to duplicate. */ RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine); /** * Free a line number structure previously allocated by a RTDbg method. * * @param pLine The line number to free. NULL is ignored. */ RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine); /** * Dump the stack of the current thread into @a pszStack. * * This could be a little slow as it reads image and debug info again for each call. * * @returns Length of string returned in @a pszStack. * @param pszStack The output buffer. * @param cbStack The size of the output buffer. * @param fFlags Future flags, MBZ. * * @remarks Not present on all systems and contexts. */ RTDECL(size_t) RTDbgStackDumpSelf(char *pszStack, size_t cbStack, uint32_t fFlags); # ifdef IN_RING3 /** @defgroup grp_rt_dbgcfg RTDbgCfg - Debugging Configuration * * The settings used when loading and processing debug info is kept in a * RTDBGCFG instance since it's generally shared for a whole debugging session * and anyhow would be a major pain to pass as individual parameters to each * call. The debugging config API not only keeps the settings information but * also provide APIs for making use of it, and in some cases, like for instance * symbol severs, retriving and maintaining it. * * @todo Work in progress - APIs are still missing, adding when needed. * * @{ */ /** Debugging configuration handle. */ typedef struct RTDBGCFGINT *RTDBGCFG; /** Pointer to a debugging configuration handle. */ typedef RTDBGCFG *PRTDBGCFG; /** NIL debug configuration handle. */ #define NIL_RTDBGCFG ((RTDBGCFG)0) /** @name RTDBGCFG_FLAGS_XXX - Debugging configuration flags. * @{ */ /** Use deferred loading. */ #define RTDBGCFG_FLAGS_DEFERRED RT_BIT_64(0) /** Don't use the symbol server (http). */ #define RTDBGCFG_FLAGS_NO_SYM_SRV RT_BIT_64(1) /** Don't use system search paths. * On windows this means not using _NT_ALT_SYMBOL_PATH, _NT_SYMBOL_PATH, * _NT_SOURCE_PATH, and _NT_EXECUTABLE_PATH. * On other systems the effect has yet to be determined. */ #define RTDBGCFG_FLAGS_NO_SYSTEM_PATHS RT_BIT_64(2) /** Don't search the debug and image paths recursively. */ #define RTDBGCFG_FLAGS_NO_RECURSIV_SEARCH RT_BIT_64(3) /** Don't search the source paths recursively. */ #define RTDBGCFG_FLAGS_NO_RECURSIV_SRC_SEARCH RT_BIT_64(4) /** @} */ /** * Debugging configuration properties. * * The search paths are using the DOS convention of semicolon as separator * character. The the special 'srv' + asterisk syntax known from the windows * debugger search paths are also supported to some extent, as is 'cache' + * asterisk. */ typedef enum RTDBGCFGPROP { /** The customary invalid 0 value. */ RTDBGCFGPROP_INVALID = 0, /** RTDBGCFG_FLAGS_XXX. * Env: _FLAGS * The environment variable can be specified as a unsigned value or one or more * mnemonics separated by spaces. */ RTDBGCFGPROP_FLAGS, /** List of paths to search for symbol files and images. * Env: _PATH */ RTDBGCFGPROP_PATH, /** List of symbol file suffixes (semicolon separated). * Env: _SUFFIXES */ RTDBGCFGPROP_SUFFIXES, /** List of paths to search for source files. * Env: _SRC_PATH */ RTDBGCFGPROP_SRC_PATH, /** End of valid values. */ RTDBGCFGPROP_END, /** The customary 32-bit type hack. */ RTDBGCFGPROP_32BIT_HACK = 0x7fffffff } RTDBGCFGPROP; /** * Configuration property change operation. */ typedef enum RTDBGCFGOP { /** Customary invalid 0 value. */ RTDBGCFGOP_INVALID = 0, /** Replace the current value with the given one. */ RTDBGCFGOP_SET, /** Append the given value to the existing one. For integer values this is * considered a bitwise OR operation. */ RTDBGCFGOP_APPEND, /** Prepend the given value to the existing one. For integer values this is * considered a bitwise OR operation. */ RTDBGCFGOP_PREPEND, /** Removes the value from the existing one. For interger values the value is * complemented and ANDed with the existing one, clearing all the specified * flags/bits. */ RTDBGCFGOP_REMOVE, /** End of valid values. */ RTDBGCFGOP_END, /** Customary 32-bit type hack. */ RTDBGCFGOP_32BIT_HACK = 0x7fffffff } RTDBGCFGOP; /** * Initializes a debugging configuration. * * @returns IPRT status code. * @param phDbgCfg Where to return the configuration handle. * @param pszEnvVarPrefix The environment variable prefix. If NULL, the * environment is not consulted. * @param fNativePaths Whether to pick up native paths from the * environment. * * @sa RTDbgCfgChangeString, RTDbgCfgChangeUInt. */ RTDECL(int) RTDbgCfgCreate(PRTDBGCFG phDbgCfg, const char *pszEnvVarPrefix, bool fNativePaths); /** * Retains a new reference to a debugging config. * * @returns New reference count. * UINT32_MAX is returned if the handle is invalid (asserted). * @param hDbgCfg The config handle. */ RTDECL(uint32_t) RTDbgCfgRetain(RTDBGCFG hDbgCfg); /** * Releases a references to a debugging config. * * @returns New reference count, if 0 the config was freed. UINT32_MAX is * returned if the handle is invalid (asserted). * @param hDbgCfg The config handle. */ RTDECL(uint32_t) RTDbgCfgRelease(RTDBGCFG hDbgCfg); /** * Changes a property value by string. * * For string values the string is used more or less as given. For integer * values and flags, it can contains both values (ORed together) or property * specific mnemonics (ORed / ~ANDed). * * @returns IPRT status code. * @retval VERR_DBG_CFG_INVALID_VALUE * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param enmOp How to change the property. * @param pszValue The property value to apply. */ RTDECL(int) RTDbgCfgChangeString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, const char *pszValue); /** * Changes a property value by unsigned integer (64-bit). * * This can only be applied to integer and flag properties. * * @returns IPRT status code. * @retval VERR_DBG_CFG_NOT_UINT_PROP * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param enmOp How to change the property. * @param uValue The property value to apply. */ RTDECL(int) RTDbgCfgChangeUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, uint64_t uValue); /** * Query a property value as string. * * Integer and flags properties are returned as a list of mnemonics if possible, * otherwise as simple hex values. * * @returns IPRT status code. * @retval VERR_BUFFER_OVERFLOW if there isn't sufficient buffer space. Nothing * is written. * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param pszValue The output buffer. * @param cbValue The size of the output buffer. */ RTDECL(int) RTDbgCfgQueryString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, char *pszValue, size_t cbValue); /** * Query a property value as unsigned integer (64-bit). * * Only integer and flags properties can be queried this way. * * @returns IPRT status code. * @retval VERR_DBG_CFG_NOT_UINT_PROP * @param hDbgCfg The debugging configuration handle. * @param enmProp The property to change. * @param puValue Where to return the value. */ RTDECL(int) RTDbgCfgQueryUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, uint64_t *puValue); /** * Log callback. * * @param hDbgCfg The debug config instance. * @param iLevel The message level. * @param pszMsg The message. * @param pvUser User argument. */ typedef DECLCALLBACKTYPE(void, FNRTDBGCFGLOG,(RTDBGCFG hDbgCfg, uint32_t iLevel, const char *pszMsg, void *pvUser)); /** Pointer to a log callback. */ typedef FNRTDBGCFGLOG *PFNRTDBGCFGLOG; /** * Sets the log callback for the configuration. * * This will fail if there is already a log callback present, unless pfnCallback * is NULL. * * @returns IPRT status code. * @param hDbgCfg The debugging configuration handle. * @param pfnCallback The callback function. NULL to unset. * @param pvUser The user argument. */ RTDECL(int) RTDbgCfgSetLogCallback(RTDBGCFG hDbgCfg, PFNRTDBGCFGLOG pfnCallback, void *pvUser); /** * Callback used by the RTDbgCfgOpen function to try out a file that was found. * * @returns On statuses other than VINF_CALLBACK_RETURN and * VERR_CALLBACK_RETURN the search will continue till the end of the * list. These status codes will not necessarily be propagated to the * caller in any consistent manner. * @retval VINF_CALLBACK_RETURN if successfully opened the file and it's time * to return * @retval VERR_CALLBACK_RETURN if we should stop searching immediately. * * @param hDbgCfg The debugging configuration handle. * @param pszFilename The path to the file that should be tried out. * @param pvUser1 First user parameter. * @param pvUser2 Second user parameter. */ typedef DECLCALLBACKTYPE(int, FNRTDBGCFGOPEN,(RTDBGCFG hDbgCfg, const char *pszFilename, void *pvUser1, void *pvUser2)); /** Pointer to a open-file callback used to the RTDbgCfgOpen functions. */ typedef FNRTDBGCFGOPEN *PFNRTDBGCFGOPEN; RTDECL(int) RTDbgCfgOpenEx(RTDBGCFG hDbgCfg, const char *pszFilename, const char *pszCacheSubDir, const char *pszUuidMappingSubDir, uint32_t fFlags, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenPeImage(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenPdb70(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, uint32_t uAge, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenPdb20(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, uint32_t uAge, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenDbg(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenDwo(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t uCrc32, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenDwoBuildId(RTDBGCFG hDbgCfg, const char *pszFilename, const uint8_t *pbBuildId, size_t cbBuildId, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenDsymBundle(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); RTDECL(int) RTDbgCfgOpenMachOImage(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2); /** @name RTDBGCFG_O_XXX - Open flags for RTDbgCfgOpen. * @{ */ /** The operative system mask. The values are RT_OPSYS_XXX. */ #define RTDBGCFG_O_OPSYS_MASK UINT32_C(0x000000ff) /** Use debuginfod style symbol servers when encountered in the path. */ #define RTDBGCFG_O_DEBUGINFOD RT_BIT_32(24) /** Same as RTDBGCFG_FLAGS_NO_SYSTEM_PATHS. */ #define RTDBGCFG_O_NO_SYSTEM_PATHS RT_BIT_32(25) /** The files may be compressed MS styled. */ #define RTDBGCFG_O_MAYBE_COMPRESSED_MS RT_BIT_32(26) /** Whether to make a recursive search. */ #define RTDBGCFG_O_RECURSIVE RT_BIT_32(27) /** We're looking for a separate debug file. */ #define RTDBGCFG_O_EXT_DEBUG_FILE RT_BIT_32(28) /** We're looking for an executable image. */ #define RTDBGCFG_O_EXECUTABLE_IMAGE RT_BIT_32(29) /** The file search should be done in an case insensitive fashion. */ #define RTDBGCFG_O_CASE_INSENSITIVE RT_BIT_32(30) /** Use Windbg style symbol servers when encountered in the path. */ #define RTDBGCFG_O_SYMSRV RT_BIT_32(31) /** Mask of valid flags. */ #define RTDBGCFG_O_VALID_MASK UINT32_C(0xff0000ff) /** @} */ /** @name Static symbol cache configuration * @{ */ /** The cache subdirectory containing the UUID mappings for .dSYM bundles. * The UUID mappings implemented by IPRT are splitting the image/dsym UUID up * into five 4 digit parts that maps to directories and one twelve digit part * that maps to a symbolic link. The symlink points to the file in the * Contents/Resources/DWARF/ directory of the .dSYM bundle for a .dSYM map, and * to the image file (Contents/MacOS/bundlename for bundles) for image map. * * According to available documentation, both lldb and gdb are able to use these * UUID maps to find debug info while debugging. See: * http://lldb.llvm.org/symbols.html */ #define RTDBG_CACHE_UUID_MAP_DIR_DSYMS "dsym-uuids" /** The cache subdirectory containing the UUID mappings for image files. */ #define RTDBG_CACHE_UUID_MAP_DIR_IMAGES "image-uuids" /** Suffix used for the cached .dSYM debug files. * In .dSYM bundles only the .dSYM/Contents/Resources/DWARF/debug-file is * copied into the cache, and in order to not clash with the stripped/rich image * file, the cache tool slaps this suffix onto the name. */ #define RTDBG_CACHE_DSYM_FILE_SUFFIX ".dwarf" /** @} */ # endif /* IN_RING3 */ /** @} */ /** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space * @{ */ /** * Creates an empty address space. * * @returns IPRT status code. * * @param phDbgAs Where to store the address space handle on success. * @param FirstAddr The first address in the address space. * @param LastAddr The last address in the address space. * @param pszName The name of the address space. */ RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName); /** * Variant of RTDbgAsCreate that takes a name format string. * * @returns IPRT status code. * * @param phDbgAs Where to store the address space handle on success. * @param FirstAddr The first address in the address space. * @param LastAddr The last address in the address space. * @param pszNameFmt The name format of the address space. * @param va Format arguments. */ RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(4, 0); /** * Variant of RTDbgAsCreate that takes a name format string. * * @returns IPRT status code. * * @param phDbgAs Where to store the address space handle on success. * @param FirstAddr The first address in the address space. * @param LastAddr The last address in the address space. * @param pszNameFmt The name format of the address space. * @param ... Format arguments. */ RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5); /** * 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 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); /** * Locks the address space for exclusive access. * * @returns IRPT status code * @param hDbgAs The address space handle. */ RTDECL(int) RTDbgAsLockExcl(RTDBGAS hDbgAs); /** * Counters the actions of one RTDbgAsUnlockExcl call. * * @returns IRPT status code * @param hDbgAs The address space handle. */ RTDECL(int) RTDbgAsUnlockExcl(RTDBGAS hDbgAs); /** * Gets the name of an address space. * * @returns read only address space name. * NULL if hDbgAs is invalid. * * @param hDbgAs The address space handle. * * @remarks Will not take any locks. */ RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs); /** * Gets the first address in an address space. * * @returns The address. * 0 if hDbgAs is invalid. * * @param hDbgAs The address space handle. * * @remarks Will not take any locks. */ RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs); /** * Gets the last address in an address space. * * @returns The address. * 0 if hDbgAs is invalid. * * @param hDbgAs The address space handle. * * @remarks Will not take any locks. */ RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs); /** * Gets the number of modules in the address space. * * This can be used together with RTDbgAsModuleByIndex * to enumerate the modules. * * @returns The number of modules. * * @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) /** @} */ /** * Links a module into the address space at the give address. * * The size of the mapping is determined using RTDbgModImageSize(). * * @returns IPRT status code. * @retval VERR_OUT_OF_RANGE if the specified address will put the module * outside the address space. * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings. * * @param hDbgAs The address space handle. * @param hDbgMod The module handle of the module to be linked in. * @param ImageAddr The address to link the module at. * @param fFlags See RTDBGASLINK_FLAGS_*. */ RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags); /** * Links a segment into the address space at the give address. * * The size of the mapping is determined using RTDbgModSegmentSize(). * * @returns IPRT status code. * @retval VERR_OUT_OF_RANGE if the specified address will put the module * outside the address space. * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings. * * @param hDbgAs The address space handle. * @param hDbgMod The module handle. * @param iSeg The segment number (0-based) of the segment to be * linked in. * @param SegAddr The address to link the segment at. * @param fFlags See RTDBGASLINK_FLAGS_*. */ RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags); /** * Unlinks all the mappings of a module from the address space. * * @returns IPRT status code. * @retval VERR_NOT_FOUND if the module wasn't found. * * @param hDbgAs The address space handle. * @param hDbgMod The module handle of the module to be unlinked. */ RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod); /** * Unlinks the mapping at the specified address. * * @returns IPRT status code. * @retval VERR_NOT_FOUND if no module or segment is mapped at that address. * * @param hDbgAs The address space handle. * @param Addr The address within the mapping to be unlinked. */ RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr); /** * Get a the handle of a module in the address space by is index. * * @returns A retained handle to the specified module. The caller must release * the returned reference. * NIL_RTDBGMOD if invalid index or handle. * * @param hDbgAs The address space handle. * @param iModule The index of the module to get. * * @remarks The module indexes may change after calls to RTDbgAsModuleLink, * RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and * RTDbgAsModuleUnlinkByAddr. */ RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule); /** * Queries mapping module information by handle. * * @returns IPRT status code. * @retval VERR_NOT_FOUND if no mapping was found at the specified address. * * @param hDbgAs The address space handle. * @param Addr Address within the mapping of the module or segment. * @param phMod Where to the return the retained module handle. * Optional. * @param pAddr Where to return the base address of the mapping. * Optional. * @param piSeg Where to return the segment index. This is set to * NIL if the entire module is mapped as a single * mapping. Optional. */ RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg); /** * Queries mapping module information by name. * * @returns IPRT status code. * @retval VERR_NOT_FOUND if no mapping was found at the specified address. * @retval VERR_OUT_OF_RANGE if the name index was out of range. * * @param hDbgAs The address space handle. * @param pszName The module name. * @param iName There can be more than one module by the same name * in an address space. This argument indicates which * is meant. (0 based) * @param phMod Where to the return the retained module handle. */ RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod); /** * Information about a mapping. * * This is used by RTDbgAsModuleGetMapByIndex. */ typedef struct RTDBGASMAPINFO { /** The mapping address. */ RTUINTPTR Address; /** The segment mapped there. * This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */ RTDBGSEGIDX iSeg; } RTDBGASMAPINFO; /** Pointer to info about an address space mapping. */ typedef RTDBGASMAPINFO *PRTDBGASMAPINFO; /** Pointer to const info about an address space mapping. */ typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO; /** * Queries mapping information for a module given by index. * * @returns IRPT status code. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_OUT_OF_RANGE if the name index was out of range. * @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned * information is incomplete. * * @param hDbgAs The address space handle. * @param iModule The index of the module to get. * @param paMappings Where to return the mapping information. The buffer * size is given by *pcMappings. * @param pcMappings IN: Size of the paMappings array. OUT: The number of * entries returned. * @param fFlags Flags for reserved for future use. MBZ. * * @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the * iModule parameter. */ RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags); /** * Adds a symbol to a module in the address space. * * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if no module was found at the specified address. * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding * custom symbols. * * @param hDbgAs The address space handle. * @param pszSymbol The symbol name. * @param Addr The address of the symbol. * @param cb The size of the symbol. * @param fFlags Symbol flags, RTDBGSYMBOLADD_F_XXX. * @param piOrdinal Where to return the symbol ordinal on success. If * the interpreter doesn't do ordinals, this will be set to * UINT32_MAX. Optional */ RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char *pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal); /** * Query a symbol by address. * * @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @retval VERR_INVALID_PARAMETER if incorrect flags. * * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to return the distance between the symbol * and address. Optional. * @param pSymbol Where to return the symbol info. * @param phMod Where to return the module handle. Optional. */ RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod); /** * Query a symbol by address. * * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * @retval VERR_INVALID_PARAMETER if incorrect flags. * * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to return the distance between the symbol * and address. Optional. * @param ppSymInfo Where to return the pointer to the allocated symbol * info. Always set. Free with RTDbgSymbolFree. * @param phMod Where to return the module handle. Optional. */ RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod); /** * Query a symbol by name. * * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if not found. * * @param hDbgAs The address space handle. * @param pszSymbol The symbol name. It is possible to limit the scope * of the search by prefixing the symbol with a module * name pattern followed by a bang (!) character. * RTStrSimplePatternNMatch is used for the matching. * @param pSymbol Where to return the symbol info. * @param phMod Where to return the module handle. Optional. */ RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod); /** * Query a symbol by name, allocating the returned symbol structure. * * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if not found. * * @param hDbgAs The address space handle. * @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more. * @param ppSymbol Where to return the pointer to the allocated * symbol info. Always set. Free with RTDbgSymbolFree. * @param phMod Where to return the module handle. Optional. */ RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol, PRTDBGMOD phMod); /** * Adds a line number to a module in the address space. * * @returns IPRT status code. See RTDbgModLineAdd for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if no module was found at the specified address. * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding * custom symbols. * * @param hDbgAs The address space handle. * @param pszFile The file name. * @param uLineNo The line number. * @param Addr The address of the symbol. * @param piOrdinal Where to return the line number ordinal on success. * If the interpreter doesn't do ordinals, this will be * set to UINT32_MAX. Optional. */ RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char *pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t *piOrdinal); /** * Query a line number by address. * * @returns IPRT status code. See RTDbgModLineAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param poffDisp Where to return the distance between the line * number and address. * @param pLine Where to return the line number information. * @param phMod Where to return the module handle. Optional. */ RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine, PRTDBGMOD phMod); /** * Query a line number by address. * * @returns IPRT status code. See RTDbgModLineAddrA for more specific ones. * @retval VERR_INVALID_HANDLE if hDbgAs is invalid. * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module. * * @param hDbgAs The address space handle. * @param Addr The address which closest symbol is requested. * @param poffDisp Where to return the distance between the line * number and address. * @param ppLine Where to return the pointer to the allocated line * number info. Always set. Free with RTDbgLineFree. * @param phMod Where to return the module handle. Optional. */ RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine, PRTDBGMOD phMod); /** @todo Missing some bits here. */ /** @} */ # ifdef IN_RING3 /** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter * @{ */ /** * Creates a module based on the default debug info container. * * This can be used to manually load a module and its symbol. The primary user * group is the debug info interpreters, which use this API to create an * efficient debug info container behind the scenes and forward all queries to * it once the info has been loaded. * * @returns IPRT status code. * * @param phDbgMod Where to return the module handle. * @param pszName The name of the module (mandatory). * @param cbSeg The size of initial segment. If zero, segments will * have to be added manually using RTDbgModSegmentAdd. * @param fFlags Flags reserved for future extensions, MBZ for now. */ RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags); RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTLDRARCH enmArch, RTDBGCFG hDbgCfg); RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTUINTPTR uSubtrahend, RTDBGCFG hDbgCfg); RTDECL(int) RTDbgModCreateFromPeImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, PRTLDRMOD phLdrMod, uint32_t cbImage, uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg); RTDECL(int) RTDbgModCreateFromDbg(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage, uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg); RTDECL(int) RTDbgModCreateFromPdb(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage, PCRTUUID pUuid, uint32_t Age, RTDBGCFG hDbgCfg); RTDECL(int) RTDbgModCreateFromDwo(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage, uint32_t uCrc32, RTDBGCFG hDbgCfg); RTDECL(int) RTDbgModCreateFromMachOImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTLDRARCH enmArch, PRTLDRMOD phLdrModIn, uint32_t cbImage, uint32_t cSegs, PCRTDBGSEGMENT paSegs, PCRTUUID pUuid, RTDBGCFG hDbgCfg, uint32_t fFlags); /** @name Flags for RTDbgModCreate and friends. * @{ */ /** Overrides the hDbgCfg settings and forces an image and/or symbol file * search. RTDbgModCreate will quietly ignore this flag. */ #define RTDBGMOD_F_NOT_DEFERRED RT_BIT_32(0) /** Mach-O: Load the __LINKEDIT segment (@sa RTLDR_O_MACHO_LOAD_LINKEDIT). */ #define RTDBGMOD_F_MACHO_LOAD_LINKEDIT RT_BIT_32(1) /** Valid flag mask. */ #define RTDBGMOD_F_VALID_MASK UINT32_C(0x00000003) /** @} */ /** * Retains another reference to the module. * * @returns New reference count, UINT32_MAX on invalid handle (asserted). * * @param hDbgMod The module handle. * * @remarks Will not take any locks. */ RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod); /** * Release a reference to the module. * * When the reference count reaches zero, the module is destroyed. * * @returns New reference count, UINT32_MAX on invalid handle (asserted). * * @param hDbgMod The module handle. The NIL handle is quietly ignored * and 0 is returned. * * @remarks Will not take any locks. */ RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod); /** * Removes all content from the debug module (container), optionally only * leaving segments and image size intact. * * This is only possible on container modules, i.e. created by RTDbgModCreate(). * * @returns IPRT status code. * @param hDbgMod The module handle. * @param fLeaveSegments Whether to leave segments (and image size) as is. */ RTDECL(int) RTDbgModRemoveAll(RTDBGMOD hDbgMod, bool fLeaveSegments); /** * Gets the module name. * * @returns Pointer to a read only string containing the name. * * @param hDbgMod The module handle. */ RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod); /** * Gets the name of the debug info file we're using. * * @returns Pointer to a read only string containing the filename, NULL if we * don't use one. * * @param hDbgMod The module handle. */ RTDECL(const char *) RTDbgModDebugFile(RTDBGMOD hDbgMod); /** * Gets the image filename (as specified by the user). * * @returns Pointer to a read only string containing the filename. * * @param hDbgMod The module handle. */ RTDECL(const char *) RTDbgModImageFile(RTDBGMOD hDbgMod); /** * Gets the image filename actually used if it differs from RTDbgModImageFile. * * @returns Pointer to a read only string containing the filename, NULL if same * as RTDBgModImageFile. * * @param hDbgMod The module handle. */ RTDECL(const char *) RTDbgModImageFileUsed(RTDBGMOD hDbgMod); /** * Checks if the loading of the debug info has been postponed. * * @returns true if postponed, false if not or invalid handle. * @param hDbgMod The module handle. */ RTDECL(bool) RTDbgModIsDeferred(RTDBGMOD hDbgMod); /** * Checks if the debug info is exports only. * * @returns true if exports only, false if not or invalid handle. * @param hDbgMod The module handle. */ RTDECL(bool) RTDbgModIsExports(RTDBGMOD hDbgMod); /** * Converts an image relative address to a segment:offset address. * * @returns Segment index on success. * NIL_RTDBGSEGIDX is returned if the module handle or the RVA are * invalid. * * @param hDbgMod The module handle. * @param uRva The image relative address to convert. * @param poffSeg Where to return the segment offset. Optional. */ RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg); /** * Gets the module tag value if any. * * @returns The tag. 0 if hDbgMod is invalid. * * @param hDbgMod The module handle. */ RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod); /** * Tags or untags the module. * * @returns IPRT status code. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * * @param hDbgMod The module handle. * @param uTag The tag value. The convention is that 0 is no tag * and any other value means it's tagged. It's adviced * to use some kind of unique number like an address * (global or string cache for instance) to avoid * collisions with other users */ RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag); /** * Image size when mapped if segments are mapped adjacently. * * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and * NE and such it's a bit odder and the answer may not make much sense for them. * * @returns Image mapped size. * RTUINTPTR_MAX is returned if the handle is invalid. * * @param hDbgMod The module handle. */ RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod); /** * Gets the image format. * * @returns Image format. * @retval RTLDRFMT_INVALID if the handle is invalid or if the format isn't known. * @param hDbgMod The debug module handle. * @sa RTLdrGetFormat */ RTDECL(RTLDRFMT) RTDbgModImageGetFormat(RTDBGMOD hDbgMod); /** * Gets the image architecture. * * @returns Image architecture. * @retval RTLDRARCH_INVALID if the handle is invalid. * @retval RTLDRARCH_WHATEVER if unknown. * @param hDbgMod The debug module handle. * @sa RTLdrGetArch */ RTDECL(RTLDRARCH) RTDbgModImageGetArch(RTDBGMOD hDbgMod); /** * Generic method for querying image properties. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all * or that specific property). The caller must handle this result. * @retval VERR_NOT_FOUND the property was not found in the module. The caller * must also normally deal with this. * @retval VERR_INVALID_FUNCTION if the function value is wrong. * @retval VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct * size in @a *pcbRet. * @retval VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size * buffer and the buffer isn't big enough. Correct size in @a *pcbRet. * @retval VERR_INVALID_HANDLE if the handle is invalid. * * @param hDbgMod The debug module handle. * @param enmProp The property to query. * @param pvBuf Pointer to the input / output buffer. In most cases * it's only used for returning data. * @param cbBuf The size of the buffer. * @param pcbRet Where to return the amount of data returned. On * buffer size errors, this is set to the correct size. * Optional. * @sa RTLdrQueryPropEx */ RTDECL(int) RTDbgModImageQueryProp(RTDBGMOD hDbgMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf, size_t *pcbRet); /** * Adds a segment to the module. Optional feature. * * This method is intended used for manually constructing debug info for a * module. The main usage is from other debug info interpreters that want to * avoid writing a debug info database and instead uses the standard container * behind the scenes. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info * interpreter. This is a common return code. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around. * @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long. * @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags. * @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations. * * @param hDbgMod The module handle. * @param uRva The image relative address of the segment. * @param cb The size of the segment. * @param pszName The segment name. Does not normally need to be * unique, although this is somewhat up to the * debug interpreter to decide. * @param fFlags Segment flags. Reserved for future used, MBZ. * @param piSeg The segment index or NIL_RTDBGSEGIDX on input. * The assigned segment index on successful return. * Optional. */ RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, uint32_t fFlags, PRTDBGSEGIDX piSeg); /** * Gets the number of segments in the module. * * This is can be used to determine the range which can be passed to * RTDbgModSegmentByIndex and derivates. * * @returns The segment relative address. * NIL_RTDBGSEGIDX if the handle is invalid. * * @param hDbgMod The module handle. */ RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod); /** * Query information about a segment. * * This can be used together with RTDbgModSegmentCount to enumerate segments. * The index starts a 0 and stops one below RTDbgModSegmentCount. * * @returns IPRT status code. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high. * @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * * @param hDbgMod The module handle. * @param iSeg The segment index. No special segments. * @param pSegInfo Where to return the segment info. The * RTDBGSEGMENT::Address member will be set to * RTUINTPTR_MAX or the load address used at link time. */ RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo); /** * Gets the size of a segment. * * This is a just a wrapper around RTDbgModSegmentByIndex. * * @returns The segment size. * RTUINTPTR_MAX is returned if either the handle and segment index are * invalid. * * @param hDbgMod The module handle. * @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed. * If RTDBGSEGIDX_RVA is used, the functions returns * the same value as RTDbgModImageSize. */ RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg); /** * Gets the image relative address of a segment. * * This is a just a wrapper around RTDbgModSegmentByIndex. * * @returns The segment relative address. * RTUINTPTR_MAX is returned if either the handle and segment index are * invalid. * * @param hDbgMod The module handle. * @param iSeg The segment index. No special segment indexes * allowed (asserted). */ RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg); /** * Adds a line number to the module. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding * custom symbols. This is a common place occurrence. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or * short. * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and * it's not inside any of the segments defined by the module. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid. * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the * end of the segment. * @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around. * @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits. * @retval VERR_DBG_DUPLICATE_SYMBOL * @retval VERR_DBG_ADDRESS_CONFLICT * * @param hDbgMod The module handle. * @param pszSymbol The symbol name. * @param iSeg The segment index. * @param off The segment offset. * @param cb The size of the symbol. Can be zero, although this * may depend somewhat on the debug interpreter. * @param fFlags Symbol flags, RTDBGSYMBOLADD_F_XXX. * @param piOrdinal Where to return the symbol ordinal on success. If * the interpreter doesn't do ordinals, this will be set to * UINT32_MAX. Optional. */ RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal); /** * Gets the symbol count. * * This can be used together wtih RTDbgModSymbolByOrdinal or * RTDbgModSymbolByOrdinalA to enumerate all the symbols. * * @returns The number of symbols in the module. * UINT32_MAX is returned if the module handle is invalid or some other * error occurs. * * @param hDbgMod The module handle. */ RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod); /** * Queries symbol information by ordinal number. * * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number. * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported. * * @param hDbgMod The module handle. * @param iOrdinal The symbol ordinal number. 0-based. The highest * number is RTDbgModSymbolCount() - 1. * @param pSymInfo Where to store the symbol information. */ RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo); /** * Queries symbol information by ordinal number. * * @returns IPRT status code. * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols. * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported. * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number. * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails. * * @param hDbgMod The module handle. * @param iOrdinal The symbol ordinal number. 0-based. The highest * number is RTDbgModSymbolCount() - 1. * @param ppSymInfo Where to store the pointer to the returned * symbol information. Always set. Free with * RTDbgSymbolFree. */ RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo); /** * Queries symbol information by address. * * The returned symbol is what the debug info interpreter considers the symbol * most applicable to the specified address. This usually means a symbol with an * address equal or lower than the requested. * * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found. * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and * it's not inside any of the segments defined by the module. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid. * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the * end of the segment. * @retval VERR_INVALID_PARAMETER if incorrect flags. * * @param hDbgMod The module handle. * @param iSeg The segment number. * @param off The offset into the segment. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to store the distance between the * specified address and the returned symbol. * Optional. * @param pSymInfo Where to store the symbol information. */ RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo); /** * Queries symbol information by address. * * The returned symbol is what the debug info interpreter considers the symbol * most applicable to the specified address. This usually means a symbol with an * address equal or lower than the requested. * * @returns IPRT status code. * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found. * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and * it's not inside any of the segments defined by the module. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid. * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the * end of the segment. * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails. * @retval VERR_INVALID_PARAMETER if incorrect flags. * * @param hDbgMod The module handle. * @param iSeg The segment index. * @param off The offset into the segment. * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX. * @param poffDisp Where to store the distance between the * specified address and the returned symbol. Optional. * @param ppSymInfo Where to store the pointer to the returned * symbol information. Always set. Free with * RTDbgSymbolFree. */ RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo); /** * Queries symbol information by symbol name. * * @returns IPRT status code. * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols. * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found. * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or * short. * * @param hDbgMod The module handle. * @param pszSymbol The symbol name. * @param pSymInfo Where to store the symbol information. */ RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo); /** * Queries symbol information by symbol name. * * @returns IPRT status code. * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols. * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found. * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or * short. * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails. * * @param hDbgMod The module handle. * @param pszSymbol The symbol name. * @param ppSymInfo Where to store the pointer to the returned * symbol information. Always set. Free with * RTDbgSymbolFree. */ RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL *ppSymInfo); /** * Adds a line number to the module. * * @returns IPRT status code. * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding * custom symbols. This should be consider a normal response. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or * empty. * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and * it's not inside any of the segments defined by the module. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid. * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the * end of the segment. * @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits. * * @param hDbgMod The module handle. * @param pszFile The file name. * @param uLineNo The line number. * @param iSeg The segment index. * @param off The segment offset. * @param piOrdinal Where to return the line number ordinal on * success. If the interpreter doesn't do ordinals, * this will be set to UINT32_MAX. Optional. */ RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal); /** * Gets the line number count. * * This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA * to enumerate all the line number information. * * @returns The number of line numbers in the module. * UINT32_MAX is returned if the module handle is invalid or some other * error occurs. * * @param hDbgMod The module handle. */ RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod); /** * Queries line number information by ordinal number. * * This can be used to enumerate the line numbers for the module. Use * RTDbgModLineCount() to figure the end of the ordinals. * * @returns IPRT status code. * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers. * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that * ordinal. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @param hDbgMod The module handle. * @param iOrdinal The line number ordinal number. * @param pLineInfo Where to store the information about the line * number. */ RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo); /** * Queries line number information by ordinal number. * * This can be used to enumerate the line numbers for the module. Use * RTDbgModLineCount() to figure the end of the ordinals. * * @returns IPRT status code. * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers. * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that * ordinal. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_NO_MEMORY if RTDbgLineAlloc fails. * * @param hDbgMod The module handle. * @param iOrdinal The line number ordinal number. * @param ppLineInfo Where to store the pointer to the returned line * number information. Always set. Free with * RTDbgLineFree. */ RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo); /** * Queries line number information by address. * * The returned line number is what the debug info interpreter considers the * one most applicable to the specified address. This usually means a line * number with an address equal or lower than the requested. * * @returns IPRT status code. * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers. * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and * it's not inside any of the segments defined by the module. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid. * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the * end of the segment. * * @param hDbgMod The module handle. * @param iSeg The segment number. * @param off The offset into the segment. * @param poffDisp Where to store the distance between the * specified address and the returned symbol. * Optional. * @param pLineInfo Where to store the line number information. */ RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo); /** * Queries line number information by address. * * The returned line number is what the debug info interpreter considers the * one most applicable to the specified address. This usually means a line * number with an address equal or lower than the requested. * * @returns IPRT status code. * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers. * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found. * @retval VERR_INVALID_HANDLE if hDbgMod is invalid. * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and * it's not inside any of the segments defined by the module. * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid. * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the * end of the segment. * @retval VERR_NO_MEMORY if RTDbgLineAlloc fails. * * @param hDbgMod The module handle. * @param iSeg The segment number. * @param off The offset into the segment. * @param poffDisp Where to store the distance between the * specified address and the returned symbol. * Optional. * @param ppLineInfo Where to store the pointer to the returned line * number information. Always set. Free with * RTDbgLineFree. */ RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo); /** * Try use unwind information to unwind one frame. * * @returns IPRT status code. Last informational status from stack reader callback. * @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information. * @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found * for the location given by iSeg:off. * * @param hDbgMod The module handle. * @param iSeg The segment number of the program counter. * @param off The offset into @a iSeg. Together with @a iSeg * this corresponds to the RTDBGUNWINDSTATE::uPc * value pointed to by @a pState. * @param pState The unwind state to work. * * @sa RTLdrUnwindFrame */ RTDECL(int) RTDbgModUnwindFrame(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTDBGUNWINDSTATE pState); /** @} */ # endif /* IN_RING3 */ /** @name Kernel Debug Info API * * This is a specialized API for obtaining symbols and structure information * about the running kernel. It is relatively OS specific. Its purpose and * operation is doesn't map all that well onto RTDbgMod, so a few dedicated * functions was created for it. * * @{ */ /** Handle to the kernel debug info. */ typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO; /** Pointer to a kernel debug info handle. */ typedef RTDBGKRNLINFO *PRTDBGKRNLINFO; /** Nil kernel debug info handle. */ #define NIL_RTDBGKRNLINFO ((RTDBGKRNLINFO)0) /** * Opens the kernel debug info. * * @returns IPRT status code. Can fail for any number of reasons. * * @param phKrnlInfo Where to return the kernel debug info handle on * success. * @param fFlags Flags reserved for future use. Must be zero. */ RTR0DECL(int) RTR0DbgKrnlInfoOpen(PRTDBGKRNLINFO phKrnlInfo, uint32_t fFlags); /** * Retains a reference to the kernel debug info handle. * * @returns New reference count, UINT32_MAX on invalid handle (asserted). * @param hKrnlInfo The kernel info handle. */ RTR0DECL(uint32_t) RTR0DbgKrnlInfoRetain(RTDBGKRNLINFO hKrnlInfo); /** * Releases a reference to the kernel debug info handle, destroying it when the * counter reaches zero. * * @returns New reference count, UINT32_MAX on invalid handle (asserted). * @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is * quietly ignored. */ RTR0DECL(uint32_t) RTR0DbgKrnlInfoRelease(RTDBGKRNLINFO hKrnlInfo); /** * Queries the offset (in bytes) of a member of a kernel structure. * * @returns IPRT status code. * @retval VINF_SUCCESS and offset at @a poffMember. * @retval VERR_NOT_FOUND if the structure or the member was not found. * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad. * @retval VERR_INVALID_POINTER if any of the pointers are bad. * * @param hKrnlInfo The kernel info handle. * @param pszModule The name of the module to search, pass NULL to * search the default kernel module(s). * @param pszStructure The structure name. * @param pszMember The member name. * @param poffMember Where to return the offset. */ RTR0DECL(int) RTR0DbgKrnlInfoQueryMember(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszStructure, const char *pszMember, size_t *poffMember); /** * Queries the value (usually the address) of a kernel symbol. * * This may go looking for the symbol in other modules, in which case it will * always check the kernel symbol table first. * * @returns IPRT status code. * @retval VINF_SUCCESS and value at @a ppvSymbol. * @retval VERR_SYMBOL_NOT_FOUND * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad. * @retval VERR_INVALID_POINTER if any of the pointers are bad. * * @param hKrnlInfo The kernel info handle. * @param pszModule The name of the module to search, pass NULL to * search the default kernel module(s). * @param pszSymbol The C name of the symbol. * On Windows NT there are the following special symbols: * - __ImageBase: The base address of the module. * - __ImageSize: The size of the module. * - __ImageNtHdrs: Address of the NT headers. * @param ppvSymbol Where to return the symbol value, passing NULL is * OK. This may be modified even on failure, in * particular, it will be set to NULL when * VERR_SYMBOL_NOT_FOUND is returned. * * @sa RTR0DbgKrnlInfoGetSymbol, RTLdrGetSymbol */ RTR0DECL(int) RTR0DbgKrnlInfoQuerySymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszSymbol, void **ppvSymbol); /** * Wrapper around RTR0DbgKrnlInfoQuerySymbol that returns the symbol. * * @return Symbol address if found, NULL if not found or some invalid parameter * or something. * @param hKrnlInfo The kernel info handle. * @param pszModule The name of the module to search, pass NULL to * search the default kernel module(s). * @param pszSymbol The C name of the symbol. * On Windows NT there are the following special symbols: * - __ImageBase: The base address of the module. * - __ImageSize: The size of the module. * - __ImageNtHdrs: Address of the NT headers. * @sa RTR0DbgKrnlInfoQuerySymbol, RTLdrGetSymbol */ RTR0DECL(void *) RTR0DbgKrnlInfoGetSymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszSymbol); /** * Queries the size (in bytes) of a kernel data type. * * @returns IPRT status code. * @retval VINF_SUCCESS and size at @a pcbType. * @retval VERR_NOT_FOUND if the type was not found. * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad. * @retval VERR_INVALID_POINTER if any of the pointers are bad. * @retval VERR_WRONG_TYPE if the type was not a valid data type (e.g. a * function) * * @param hKrnlInfo The kernel info handle. * @param pszModule The name of the module to search, pass NULL to * search the default kernel module(s). * @param pszType The type name. * @param pcbType Where to return the size of the type. */ RTR0DECL(int) RTR0DbgKrnlInfoQuerySize(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszType, size_t *pcbType); /** @} */ /** @} */ RT_C_DECLS_END #endif /* !IPRT_INCLUDED_dbg_h */