/* $Id: $ */ /** @file * * kProfile Mark 2 - Debug Info Reader. * * Copyright (c) 2006 knut st. osmundsen * * * 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; either version 2 of the License, or * (at your option) any later version. * * 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, write to the Free Software * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA * */ #ifndef __iprt_dbg_h__ #define __iprt_dbg_h__ #include __BEGIN_DECLS /** @defgroup grp_rt_dbg Debug Info Reader * @addtogroup grp_rt * @{ */ /** The max filename path length used by the debug reader. */ #define RTDBG_PATH_MAX 260 /** The max symbol name length used by the debug reader. */ #define RTDBG_SYMBOL_MAX 384 /** @name Special Segments * @{ */ /** Relative Virtual Address. * The specified offset is relative to the image base. The image base is the lowest memory * address used by the image when loaded with the address assignments indicated in the image. */ #define RTDBGSEG_RVA (-1) /** Absolute segment. The offset isn't relative to anything. */ #define RTDBGSEG_ABS (-2) /** @} */ /** * Line number details. */ typedef struct RTDBGLINE { /** The relative virtual address. */ RTUINTPTR RVA; /** The offset into the segment. */ RTUINTPTR offSegment; /** The segment number. */ int32_t iSegment; /** The Line number. */ uint32_t iLine; /** The length of the filename. */ uint16_t cchFile; /** The name of the file this line number relates to. */ char szFile[RTDBG_PATH_MAX]; } RTDBGLINE; /** Pointer to line number details. */ typedef RTDBGLINE *PRTDBGLINE; /** Pointer to const line number details. */ typedef const RTDBGLINE *PCRTDBGLINE; /** Pointer to a pointer to line number details. */ typedef PRTDBGLINE *PPRTDBGLINE; /** * Duplicates a line number. * * To save heap space, the returned line number will not own more heap space * than it strictly need to. So, it's not possible to append stuff to the symbol * or anything of that kind. * * @returns Pointer to the duplicate. * This must be freed using RTDbgSymbolFree(). * @param pLine The line number to be duplicated. */ RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine); /** * Frees a line number obtained from the RTDbg API. * * @returns VINF_SUCCESS on success. * @returns VERR_INVALID_POINTER if a NULL pointer or an !VALID_PTR() is passed in. * * @param pLine The line number to be freed. */ RTDECL(int) RTDbgLineFree(PRTDBGLINE pLine); /** @name Symbol Flags. * @{ */ /** The symbol is weak. */ #define RTDBGSYM_FLAGS_WEAK BIT(0) /** The symbol is absolute. * (This also indicated by the segment number.) */ #define RTDBGSYM_FLAGS_ABS BIT(1) /** The symbol is exported. */ #define RTDBGSYM_FLAGS_EXPORTED BIT(2) /** The symbol is a function/method/procedure/whatever-executable-code. */ #define RTDBGSYM_FLAGS_CODE BIT(3) /** The symbol is some kind of data. */ #define RTDBGSYM_FLAGS_DATA BIT(4) /** @} */ /** * Symbol details. */ typedef struct RTDBGSYMBOL { /** The relative virtual address. */ RTUINTPTR RVA; /** The symbol size. * This is not a reliable field, it could be a bad guess. Ignore if zero. */ RTUINTPTR cb; /** The offset into the segment. */ RTUINTPTR offSegment; /** The segment number. */ int32_t iSegment; /** The symbol flags. */ uint32_t fFlags; /** @todo type info? */ /** The length of the symbol name. */ uint16_t cchName; /** The symbol name. */ char szName[RTDBG_SYMBOL_MAX]; } RTDBGSYMBOL; /** Pointer to symbol details. */ typedef RTDBGSYMBOL *PRTDBGSYMBOL; /** Pointer to const symbol details. */ typedef const RTDBGSYMBOL *PCRTDBGSYMBOL; /** Pointer to a pointer to symbol details. */ typedef PRTDBGSYMBOL *PPRTDBGSYMBOL; /** * Duplicates a symbol. * * To save heap space, the returned symbol will not own more heap space than * it strictly need to. So, it's not possible to append stuff to the symbol * or anything of that kind. * * @returns Pointer to the duplicate. * This must be freed using RTDbgSymbolFree(). * @param pSymbol The symbol to be freed. */ RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymbol); /** * Frees a symbol obtained from the RTDbg API. * * @returns VINF_SUCCESS on success. * @returns VERR_INVALID_POINTER if a NULL pointer or an !VALID_PTR() is passed in. * * @param pSymbol The symbol to be freed. */ RTDECL(int) RTDbgSymbolFree(PRTDBGSYMBOL pSymbol); /** A debug module handle. */ typedef struct RTDBGMOD *PRTDBGMOD; /** * Opens the debug info for a specified executable module. * * @returns IPRT status code. * @param pszModulePath The path to the executable module. * @param ppDbgMod Where to store the debug module handle. */ RTDECL(int) RTDbgModuleOpen(const char *pszModulePath, PRTDBGMOD *ppDbgMod); /** * Closes the module. * * @returns IPRT status code. * @param pMod The module handle. */ RTDECL(int) RTDbgModuleClose(PRTDBGMOD pMod); /** * Gets a symbol by segment:offset. * This will be approximated to the nearest symbol if there is no exact match. * * @returns IPRT status code. * @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. */ RTDECL(int) RTDbgModuleQuerySymbol(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PRTDBGSYMBOL pSym); /** * Gets & allocates a symbol by segment:offset. * This will be approximated to the nearest symbol if there is no exact match. * * @returns IPRT status code. * @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 ppSym Where to store the pointer to the symbol info. * Free the returned symbol using RTDbgSymbolFree(). */ RTDECL(int) RTDbgModuleQuerySymbolA(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PPRTDBGSYMBOL ppSym); /** * Gets a line number entry by segment:offset. * This will be approximated to the nearest line number there is no exact match. * * @returns IPRT status code. * @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. */ RTDECL(int) RTDbgModuleQueryLine(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PRTDBGLINE pLine); /** * Gets & allocates a line number entry by segment:offset. * This will be approximated to the nearest line number there is no exact match. * * @returns IPRT status code. * @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 ppLine Where to store the pointer to the line number info. * Free the returned line number using RTDbgLineFree(). */ RTDECL(int) RTDbgModuleQueryLineA(PRTDBGMOD pMod, int32_t iSegment, RTUINTPTR off, PPRTDBGLINE ppLine); __END_DECLS /** @} */ #endif