1 | /* $Id: dbgmod.h 28800 2010-04-27 08:22:32Z vboxsync $ */
|
---|
2 | /** @file
|
---|
3 | * IPRT - Internal Header for RTDbgMod and the associated interpreters.
|
---|
4 | */
|
---|
5 |
|
---|
6 | /*
|
---|
7 | * Copyright (C) 2008-2009 Oracle Corporation
|
---|
8 | *
|
---|
9 | * This file is part of VirtualBox Open Source Edition (OSE), as
|
---|
10 | * available from http://www.virtualbox.org. This file is free software;
|
---|
11 | * you can redistribute it and/or modify it under the terms of the GNU
|
---|
12 | * General Public License (GPL) as published by the Free Software
|
---|
13 | * Foundation, in version 2 as it comes in the "COPYING" file of the
|
---|
14 | * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
|
---|
15 | * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
|
---|
16 | *
|
---|
17 | * The contents of this file may alternatively be used under the terms
|
---|
18 | * of the Common Development and Distribution License Version 1.0
|
---|
19 | * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
|
---|
20 | * VirtualBox OSE distribution, in which case the provisions of the
|
---|
21 | * CDDL are applicable instead of those of the GPL.
|
---|
22 | *
|
---|
23 | * You may elect to license modified versions of this file under the
|
---|
24 | * terms and conditions of either the GPL or the CDDL or both.
|
---|
25 | */
|
---|
26 |
|
---|
27 | #ifndef ___internal_dbgmod_h
|
---|
28 | #define ___internal_dbgmod_h
|
---|
29 |
|
---|
30 | #include <iprt/types.h>
|
---|
31 | #include <iprt/critsect.h>
|
---|
32 | #include "internal/magics.h"
|
---|
33 |
|
---|
34 | RT_C_DECLS_BEGIN
|
---|
35 |
|
---|
36 | /** @addtogroup grp_rt_dbgmod
|
---|
37 | * @internal
|
---|
38 | * @{
|
---|
39 | */
|
---|
40 |
|
---|
41 |
|
---|
42 | /** Pointer to the internal module structure. */
|
---|
43 | typedef struct RTDBGMODINT *PRTDBGMODINT;
|
---|
44 |
|
---|
45 | /**
|
---|
46 | * Virtual method table for executable image interpreters.
|
---|
47 | */
|
---|
48 | typedef struct RTDBGMODVTIMG
|
---|
49 | {
|
---|
50 | /** Magic number (RTDBGMODVTIMG_MAGIC). */
|
---|
51 | uint32_t u32Magic;
|
---|
52 | /** Mask of supported executable image types, see grp_rt_exe_img_type.
|
---|
53 | * Used to speed up the search for a suitable interpreter. */
|
---|
54 | uint32_t fSupports;
|
---|
55 | /** The name of the interpreter. */
|
---|
56 | const char *pszName;
|
---|
57 |
|
---|
58 | /**
|
---|
59 | * Try open the image.
|
---|
60 | *
|
---|
61 | * This combines probing and opening.
|
---|
62 | *
|
---|
63 | * @returns IPRT status code. No informational returns defined.
|
---|
64 | *
|
---|
65 | * @param pMod Pointer to the module that is being opened.
|
---|
66 | *
|
---|
67 | * The RTDBGMOD::pszDbgFile member will point to
|
---|
68 | * the filename of any debug info we're aware of
|
---|
69 | * on input. Also, or alternatively, it is expected
|
---|
70 | * that the interpreter will look for debug info in
|
---|
71 | * the executable image file when present and that it
|
---|
72 | * may ask the image interpreter for this when it's
|
---|
73 | * around.
|
---|
74 | *
|
---|
75 | * Upon successful return the method is expected to
|
---|
76 | * initialize pDbgOps and pvDbgPriv.
|
---|
77 | */
|
---|
78 | DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
|
---|
79 |
|
---|
80 | /**
|
---|
81 | * Close the interpreter, freeing all associated resources.
|
---|
82 | *
|
---|
83 | * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
|
---|
84 | * to NULL upon return.
|
---|
85 | *
|
---|
86 | * @param pMod Pointer to the module structure.
|
---|
87 | */
|
---|
88 | DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
|
---|
89 |
|
---|
90 | } RTDBGMODVTIMG;
|
---|
91 | /** Pointer to a const RTDBGMODVTIMG. */
|
---|
92 | typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
|
---|
93 |
|
---|
94 |
|
---|
95 | /**
|
---|
96 | * Virtual method table for debug info interpreters.
|
---|
97 | */
|
---|
98 | typedef struct RTDBGMODVTDBG
|
---|
99 | {
|
---|
100 | /** Magic number (RTDBGMODVTDBG_MAGIC). */
|
---|
101 | uint32_t u32Magic;
|
---|
102 | /** Mask of supported debug info types, see grp_rt_dbg_type.
|
---|
103 | * Used to speed up the search for a suitable interpreter. */
|
---|
104 | uint32_t fSupports;
|
---|
105 | /** The name of the interpreter. */
|
---|
106 | const char *pszName;
|
---|
107 |
|
---|
108 | /**
|
---|
109 | * Try open the image.
|
---|
110 | *
|
---|
111 | * This combines probing and opening.
|
---|
112 | *
|
---|
113 | * @returns IPRT status code. No informational returns defined.
|
---|
114 | *
|
---|
115 | * @param pMod Pointer to the module that is being opened.
|
---|
116 | *
|
---|
117 | * The RTDBGMOD::pszDbgFile member will point to
|
---|
118 | * the filename of any debug info we're aware of
|
---|
119 | * on input. Also, or alternatively, it is expected
|
---|
120 | * that the interpreter will look for debug info in
|
---|
121 | * the executable image file when present and that it
|
---|
122 | * may ask the image interpreter for this when it's
|
---|
123 | * around.
|
---|
124 | *
|
---|
125 | * Upon successful return the method is expected to
|
---|
126 | * initialize pDbgOps and pvDbgPriv.
|
---|
127 | */
|
---|
128 | DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
|
---|
129 |
|
---|
130 | /**
|
---|
131 | * Close the interpreter, freeing all associated resources.
|
---|
132 | *
|
---|
133 | * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
|
---|
134 | * to NULL upon return.
|
---|
135 | *
|
---|
136 | * @param pMod Pointer to the module structure.
|
---|
137 | */
|
---|
138 | DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
|
---|
139 |
|
---|
140 |
|
---|
141 |
|
---|
142 | /**
|
---|
143 | * Converts an image relative virtual address address to a segmented address.
|
---|
144 | *
|
---|
145 | * @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
|
---|
146 | * @param pMod Pointer to the module structure.
|
---|
147 | * @param uRva The image relative address to convert.
|
---|
148 | * @param poffSeg Where to return the segment offset. Optional.
|
---|
149 | */
|
---|
150 | DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff)(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
|
---|
151 |
|
---|
152 | /**
|
---|
153 | * Image size when mapped if segments are mapped adjecently.
|
---|
154 | *
|
---|
155 | * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
|
---|
156 | * NE and such it's a bit odder and the answer may not make much sense for them.
|
---|
157 | *
|
---|
158 | * @returns Image mapped size.
|
---|
159 | * @param pMod Pointer to the module structure.
|
---|
160 | */
|
---|
161 | DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize)(PRTDBGMODINT pMod);
|
---|
162 |
|
---|
163 |
|
---|
164 |
|
---|
165 | /**
|
---|
166 | * Adds a segment to the module (optional).
|
---|
167 | *
|
---|
168 | * @returns IPRT status code.
|
---|
169 | * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
|
---|
170 | * @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
|
---|
171 | *
|
---|
172 | * @param pMod Pointer to the module structure.
|
---|
173 | * @param uRva The segment image relative address.
|
---|
174 | * @param cb The segment size.
|
---|
175 | * @param pszName The segment name.
|
---|
176 | * @param cchName The length of the segment name.
|
---|
177 | * @param fFlags Segment flags.
|
---|
178 | * @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
|
---|
179 | * The assigned segment index on successful return.
|
---|
180 | * Optional.
|
---|
181 | */
|
---|
182 | DECLCALLBACKMEMBER(int, pfnSegmentAdd)(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
|
---|
183 | uint32_t fFlags, PRTDBGSEGIDX piSeg);
|
---|
184 |
|
---|
185 | /**
|
---|
186 | * Gets the segment count.
|
---|
187 | *
|
---|
188 | * @returns Number of segments.
|
---|
189 | * @retval NIL_RTDBGSEGIDX if unknown.
|
---|
190 | *
|
---|
191 | * @param pMod Pointer to the module structure.
|
---|
192 | */
|
---|
193 | DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnSegmentCount)(PRTDBGMODINT pMod);
|
---|
194 |
|
---|
195 | /**
|
---|
196 | * Gets information about a segment.
|
---|
197 | *
|
---|
198 | * @returns IPRT status code.
|
---|
199 | * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
|
---|
200 | *
|
---|
201 | * @param pMod Pointer to the module structure.
|
---|
202 | * @param iSeg The segment.
|
---|
203 | * @param pSegInfo Where to store the segment information.
|
---|
204 | */
|
---|
205 | DECLCALLBACKMEMBER(int, pfnSegmentByIndex)(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
|
---|
206 |
|
---|
207 |
|
---|
208 |
|
---|
209 | /**
|
---|
210 | * Adds a symbol to the module (optional).
|
---|
211 | *
|
---|
212 | * @returns IPRT code.
|
---|
213 | * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
|
---|
214 | *
|
---|
215 | * @param pMod Pointer to the module structure.
|
---|
216 | * @param pszSymbol The symbol name.
|
---|
217 | * @param cchSymbol The length for the symbol name.
|
---|
218 | * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
|
---|
219 | * @param off The offset into the segment.
|
---|
220 | * @param cb The area covered by the symbol. 0 is fine.
|
---|
221 | * @param fFlags Flags.
|
---|
222 | * @param piOrdinal Where to return the symbol ordinal on success. If the
|
---|
223 | * interpreter doesn't do ordinals, this will be set to
|
---|
224 | * UINT32_MAX. Optional
|
---|
225 | */
|
---|
226 | DECLCALLBACKMEMBER(int, pfnSymbolAdd)(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol,
|
---|
227 | uint32_t iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags,
|
---|
228 | uint32_t *piOrdinal);
|
---|
229 |
|
---|
230 | /**
|
---|
231 | * Gets the number of symbols in the module.
|
---|
232 | *
|
---|
233 | * This is used for figuring out the max value to pass to pfnSymbolByIndex among
|
---|
234 | * other things.
|
---|
235 | *
|
---|
236 | * @returns The number of symbols, UINT32_MAX if not known/supported.
|
---|
237 | *
|
---|
238 | * @param pMod Pointer to the module structure.
|
---|
239 | */
|
---|
240 | DECLCALLBACKMEMBER(uint32_t, pfnSymbolCount)(PRTDBGMODINT pMod);
|
---|
241 |
|
---|
242 | /**
|
---|
243 | * Queries symbol information by ordinal number.
|
---|
244 | *
|
---|
245 | * @returns IPRT status code.
|
---|
246 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
247 | * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
|
---|
248 | * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
|
---|
249 | * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at that index.
|
---|
250 | *
|
---|
251 | * @param pMod Pointer to the module structure.
|
---|
252 | * @param iOrdinal The symbol ordinal number.
|
---|
253 | * @param pSymInfo Where to store the symbol information.
|
---|
254 | */
|
---|
255 | DECLCALLBACKMEMBER(int, pfnSymbolByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
|
---|
256 |
|
---|
257 | /**
|
---|
258 | * Queries symbol information by symbol name.
|
---|
259 | *
|
---|
260 | * @returns IPRT status code.
|
---|
261 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
262 | * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
|
---|
263 | * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
|
---|
264 | *
|
---|
265 | * @param pMod Pointer to the module structure.
|
---|
266 | * @param pszSymbol The symbol name.
|
---|
267 | * @param cchSymbol The length of the symbol name.
|
---|
268 | * @param pSymInfo Where to store the symbol information.
|
---|
269 | */
|
---|
270 | DECLCALLBACKMEMBER(int, pfnSymbolByName)(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol, PRTDBGSYMBOL pSymInfo);
|
---|
271 |
|
---|
272 | /**
|
---|
273 | * Queries symbol information by address.
|
---|
274 | *
|
---|
275 | * The returned symbol is what the debug info interpreter consideres the symbol
|
---|
276 | * most applicable to the specified address. This usually means a symbol with an
|
---|
277 | * address equal or lower than the requested.
|
---|
278 | *
|
---|
279 | * @returns IPRT status code.
|
---|
280 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
281 | * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
|
---|
282 | * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
|
---|
283 | *
|
---|
284 | * @param pMod Pointer to the module structure.
|
---|
285 | * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
|
---|
286 | * @param off The offset into the segment.
|
---|
287 | * @param poffDisp Where to store the distance between the specified address
|
---|
288 | * and the returned symbol. Optional.
|
---|
289 | * @param pSymInfo Where to store the symbol information.
|
---|
290 | */
|
---|
291 | DECLCALLBACKMEMBER(int, pfnSymbolByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
|
---|
292 |
|
---|
293 |
|
---|
294 |
|
---|
295 | /**
|
---|
296 | * Adds a line number to the module (optional).
|
---|
297 | *
|
---|
298 | * @returns IPRT status code.
|
---|
299 | * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
|
---|
300 | *
|
---|
301 | * @param pMod Pointer to the module structure.
|
---|
302 | * @param pszFile The filename.
|
---|
303 | * @param cchFile The length of the filename.
|
---|
304 | * @param uLineNo The line number.
|
---|
305 | * @param iSeg The segment number (0-based).
|
---|
306 | * @param off The offset into the segment.
|
---|
307 | * @param piOrdinal Where to return the line number ordinal on success. If
|
---|
308 | * the interpreter doesn't do ordinals, this will be set to
|
---|
309 | * UINT32_MAX. Optional
|
---|
310 | */
|
---|
311 | DECLCALLBACKMEMBER(int, pfnLineAdd)(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
|
---|
312 | uint32_t iSeg, RTUINTPTR off, uint32_t *piOrdinal);
|
---|
313 |
|
---|
314 | /**
|
---|
315 | * Gets the number of line numbers in the module.
|
---|
316 | *
|
---|
317 | * @returns The number or UINT32_MAX if not known/supported.
|
---|
318 | *
|
---|
319 | * @param pMod Pointer to the module structure.
|
---|
320 | */
|
---|
321 | DECLCALLBACKMEMBER(uint32_t, pfnLineCount)(PRTDBGMODINT pMod);
|
---|
322 |
|
---|
323 | /**
|
---|
324 | * Queries line number information by ordinal number.
|
---|
325 | *
|
---|
326 | * @returns IPRT status code.
|
---|
327 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
328 | * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
|
---|
329 | * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
|
---|
330 | * ordinal.
|
---|
331 | *
|
---|
332 | * @param pMod Pointer to the module structure.
|
---|
333 | * @param iOrdinal The line number ordinal number.
|
---|
334 | * @param pLineInfo Where to store the information about the line number.
|
---|
335 | */
|
---|
336 | DECLCALLBACKMEMBER(int, pfnLineByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
|
---|
337 |
|
---|
338 | /**
|
---|
339 | * Queries line number information by address.
|
---|
340 | *
|
---|
341 | * @returns IPRT status code.
|
---|
342 | * @retval VINF_SUCCESS on success, no informational status code.
|
---|
343 | * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
|
---|
344 | * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
|
---|
345 | *
|
---|
346 | * @param pMod Pointer to the module structure.
|
---|
347 | * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
|
---|
348 | * @param off The offset into the segment.
|
---|
349 | * @param poffDisp Where to store the distance between the specified address
|
---|
350 | * and the returned line number. Optional.
|
---|
351 | * @param pLineInfo Where to store the information about the closest line
|
---|
352 | * number.
|
---|
353 | */
|
---|
354 | DECLCALLBACKMEMBER(int, pfnLineByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
|
---|
355 |
|
---|
356 |
|
---|
357 | /** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
|
---|
358 | uint32_t u32EndMagic;
|
---|
359 | } RTDBGMODVTDBG;
|
---|
360 | /** Pointer to a const RTDBGMODVTDBG. */
|
---|
361 | typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
|
---|
362 |
|
---|
363 |
|
---|
364 | /**
|
---|
365 | * Debug module structure.
|
---|
366 | */
|
---|
367 | typedef struct RTDBGMODINT
|
---|
368 | {
|
---|
369 | /** Magic value (RTDBGMOD_MAGIC). */
|
---|
370 | uint32_t u32Magic;
|
---|
371 | /** The number of reference there are to this module.
|
---|
372 | * This is used to perform automatic cleanup and sharing. */
|
---|
373 | uint32_t volatile cRefs;
|
---|
374 | /** The module tag. */
|
---|
375 | uint64_t uTag;
|
---|
376 | /** The module name (short). */
|
---|
377 | char const *pszName;
|
---|
378 | /** The module filename. Can be NULL. */
|
---|
379 | char const *pszImgFile;
|
---|
380 | /** The debug info file (if external). Can be NULL. */
|
---|
381 | char const *pszDbgFile;
|
---|
382 |
|
---|
383 | /** Critical section serializing access to the module. */
|
---|
384 | RTCRITSECT CritSect;
|
---|
385 |
|
---|
386 | /** The method table for the executable image interpreter. */
|
---|
387 | PCRTDBGMODVTIMG pImgVt;
|
---|
388 | /** Pointer to the private data of the executable image interpreter. */
|
---|
389 | void *pvImgPriv;
|
---|
390 |
|
---|
391 | /** The method table for the debug info interpreter. */
|
---|
392 | PCRTDBGMODVTDBG pDbgVt;
|
---|
393 | /** Pointer to the private data of the debug info interpreter. */
|
---|
394 | void *pvDbgPriv;
|
---|
395 |
|
---|
396 | } RTDBGMODINT;
|
---|
397 | /** Pointer to an debug module structure. */
|
---|
398 | typedef RTDBGMODINT *PRTDBGMODINT;
|
---|
399 |
|
---|
400 |
|
---|
401 | extern DECLHIDDEN(RTSTRCACHE) g_hDbgModStrCache;
|
---|
402 | extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
|
---|
403 |
|
---|
404 | int rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
|
---|
405 |
|
---|
406 | /** @} */
|
---|
407 |
|
---|
408 | RT_C_DECLS_END
|
---|
409 |
|
---|
410 | #endif
|
---|
411 |
|
---|