1 /* $Id: kDbg.h 29 2009-07-01 20:30:29Z bird $ */ 2 /** @file 3 * kDbg - The Debug Info Reader. 4 */ 5 6 /* 7 * Copyright (c) 2006-2007 Knut St. Osmundsen <bird-kStuff-spamix@anduin.net> 8 * 9 * Permission is hereby granted, free of charge, to any person 10 * obtaining a copy of this software and associated documentation 11 * files (the "Software"), to deal in the Software without 12 * restriction, including without limitation the rights to use, 13 * copy, modify, merge, publish, distribute, sublicense, and/or sell 14 * copies of the Software, and to permit persons to whom the 15 * Software is furnished to do so, subject to the following 16 * conditions: 17 * 18 * The above copyright notice and this permission notice shall be 19 * included in all copies or substantial portions of the Software. 20 * 21 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, 22 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES 23 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND 24 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT 25 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, 26 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 27 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR 28 * OTHER DEALINGS IN THE SOFTWARE. 29 */ 30 31 #ifndef ___k_kDbg_h___ 32 #define ___k_kDbg_h___ 33 34 #include <k/kDefs.h> 35 #include <k/kTypes.h> 36 #include <k/kRdr.h> 37 38 #ifdef __cplusplus 39 extern "C" { 40 #endif 41 42 /** @defgroup grp_kDbg Debug Info Reader 43 * @{ 44 */ 45 46 /** @def KDBG_DECL 47 * Declares a kDbg function according to build context. 48 * @param type The return type. 49 */ 50 #if defined(KDBG_BUILDING_DYNAMIC) 51 # define KDBG_DECL(type) K_DECL_EXPORT(type) 52 #elif defined(KDBG_BUILT_DYNAMIC) 53 # define KDBG_DECL(type) K_DECL_IMPORT(type) 54 #else 55 # define KDBG_DECL(type) type 56 #endif 57 58 59 /** The kDbg address type. */ 60 typedef KU64 KDBGADDR; 61 /** Pointer to a kDbg address. */ 62 typedef KDBGADDR *PKDBGADDR; 63 /** Pointer to a const kDbg address. */ 64 typedef const KDBGADDR *PCKDBGADDR; 65 /** @def KDBGADDR_PRI 66 * printf format type. */ 67 #define KDBGADDR_PRI KX64_PRI 68 /** @def KDBGADDR_MAX 69 * Max kDbg address value. */ 70 #define KDBGADDR_MAX KU64_C(0xfffffffffffffffe) 71 /** @def KDBGADDR_C 72 * kDbg address constant. 73 * @param c The constant value. */ 74 #define KDBGADDR_C(c) KU64_C(c) 75 /** NIL address. */ 76 #define NIL_KDBGADDR KU64_MAX 77 78 79 /** @name Special Segments 80 * @{ */ 81 /** Relative Virtual Address. 82 * The specified offset is relative to the image base. The image base is the lowest memory 83 * address used by the image when loaded with the address assignments indicated in the image. */ 84 #define KDBGSEG_RVA (-1) 85 /** Absolute segment. The offset isn't relative to anything. */ 86 #define KDBGSEG_ABS (-2) 87 /** @} */ 88 89 90 /** The max filename path length used by the debug reader. */ 91 #define KDBG_PATH_MAX 260 92 93 /** 94 * Line number details. 95 */ 96 typedef struct KDBGLINE 97 { 98 /** The relative virtual address. */ 99 KDBGADDR RVA; 100 /** The offset into the segment. */ 101 KDBGADDR offSegment; 102 /** The segment number. */ 103 KI32 iSegment; 104 /** The Line number. */ 105 KU32 iLine; 106 /** The actual size of this structure. */ 107 KU16 cbSelf; 108 /** The length of the filename. */ 109 KU16 cchFile; 110 /** The name of the file this line number relates to. */ 111 char szFile[KDBG_PATH_MAX]; 112 } KDBGLINE; 113 /** Pointer to line number details. */ 114 typedef KDBGLINE *PKDBGLINE; 115 /** Pointer to const line number details. */ 116 typedef const KDBGLINE *PCKDBGLINE; 117 /** Pointer to a pointer to line number details. */ 118 typedef PKDBGLINE *PPKDBGLINE; 119 120 /** 121 * Duplicates a line number. 122 * 123 * To save heap space, the returned line number will not own more heap space 124 * than it strictly need to. So, it's not possible to append stuff to the symbol 125 * or anything of that kind. 126 * 127 * @returns Pointer to the duplicate. 128 * This must be freed using RTDbgSymbolFree(). 129 * @param pLine The line number to be duplicated. 130 */ 131 KDBG_DECL(PKDBGLINE) kDbgLineDup(PCKDBGLINE pLine); 132 133 /** 134 * Frees a line number obtained from the RTDbg API. 135 * 136 * @returns VINF_SUCCESS on success. 137 * @returns KERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in. 138 * 139 * @param pLine The line number to be freed. 140 */ 141 KDBG_DECL(int) kDbgLineFree(PKDBGLINE pLine); 142 143 144 /** @name Symbol Flags. 145 * @{ */ 146 /** The symbol is weak. */ 147 #define KDBGSYM_FLAGS_WEAK KU32_C(0x00000000) 148 /** The symbol is absolute. 149 * (This also indicated by the segment number.) */ 150 #define KDBGSYM_FLAGS_ABS KU32_C(0x00000001) 151 /** The symbol is exported. */ 152 #define KDBGSYM_FLAGS_EXPORTED KU32_C(0x00000002) 153 /** The symbol is a function/method/procedure/whatever-executable-code. */ 154 #define KDBGSYM_FLAGS_CODE KU32_C(0x00000004) 155 /** The symbol is some kind of data. */ 156 #define KDBGSYM_FLAGS_DATA KU32_C(0x00000008) 157 /** @} */ 158 159 /** The max symbol name length used by the debug reader. */ 160 #define KDBG_SYMBOL_MAX 384 161 162 /** 163 * Symbol details. 164 */ 165 typedef struct KDBGSYMBOL 166 { 167 /** The adddress of this symbol in the relevant space. 168 * This is NIL_KDBGADDR unless the information was 169 * returned by a kDbgSpace API. */ 170 KDBGADDR Address; 171 /** The relative virtual address. */ 172 KDBGADDR RVA; 173 /** The symbol size. 174 * This is not a reliable field, it could be a bad guess. Ignore if zero. */ 175 KDBGADDR cb; 176 /** The offset into the segment. */ 177 KDBGADDR offSegment; 178 /** The segment number. */ 179 KI32 iSegment; 180 /** The symbol flags. */ 181 KU32 fFlags; 182 /** @todo type info. */ 183 /** The actual size of this structure. */ 184 KU16 cbSelf; 185 /** The length of the symbol name. */ 186 KU16 cchName; 187 /** The symbol name. */ 188 char szName[KDBG_SYMBOL_MAX]; 189 } KDBGSYMBOL; 190 /** Pointer to symbol details. */ 191 typedef KDBGSYMBOL *PKDBGSYMBOL; 192 /** Pointer to const symbol details. */ 193 typedef const KDBGSYMBOL *PCKDBGSYMBOL; 194 /** Pointer to a pointer to symbol details. */ 195 typedef PKDBGSYMBOL *PPKDBGSYMBOL; 196 197 /** 198 * Duplicates a symbol. 199 * 200 * To save heap space, the returned symbol will not own more heap space than 201 * it strictly need to. So, it's not possible to append stuff to the symbol 202 * or anything of that kind. 203 * 204 * @returns Pointer to the duplicate. 205 * This must be freed using kDbgSymbolFree(). 206 * @param pSymbol The symbol to be freed. 207 */ 208 KDBG_DECL(PKDBGSYMBOL) kDbgSymbolDup(PCKDBGSYMBOL pSymbol); 209 210 /** 211 * Frees a symbol obtained from the kDbg API. 212 * 213 * @returns VINF_SUCCESS on success. 214 * @returns KERR_INVALID_POINTER if a NULL pointer or an !KDBG_VALID_PTR() is passed in. 215 * 216 * @param pSymbol The symbol to be freed. 217 */ 218 KDBG_DECL(int) kDbgSymbolFree(PKDBGSYMBOL pSymbol); 219 220 221 /** Pointer to a debug module. */ 222 typedef struct KDBGMOD *PKDBGMOD; 223 /** Pointer to a debug module pointer. */ 224 typedef PKDBGMOD *PPKDBGMOD; 225 226 227 KDBG_DECL(int) kDbgModuleOpen(PPKDBGMOD ppDbgMod, const char *pszFilename, struct KLDRMOD *pLdrMod); 228 KDBG_DECL(int) kDbgModuleOpenFile(PPKDBGMOD ppDbgMod, PKRDR pRdr, struct KLDRMOD *pLdrMod); 229 KDBG_DECL(int) kDbgModuleOpenFilePart(PPKDBGMOD ppDbgMod, PKRDR pRdr, KFOFF off, KFOFF cb, struct KLDRMOD *pLdrMod); 230 KDBG_DECL(int) kDbgModuleClose(PKDBGMOD pMod); 231 KDBG_DECL(int) kDbgModuleQuerySymbol(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PKDBGSYMBOL pSym); 232 KDBG_DECL(int) kDbgModuleQuerySymbolA(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PPKDBGSYMBOL ppSym); 233 KDBG_DECL(int) kDbgModuleQueryLine(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PKDBGLINE pLine); 234 KDBG_DECL(int) kDbgModuleQueryLineA(PKDBGMOD pMod, KI32 iSegment, KDBGADDR off, PPKDBGLINE ppLine); 235 236 237 /** @} */ 238 239 #ifdef __cplusplus 240 } 241 #endif 242 243 #endif 244