VirtualBox

source: vbox/trunk/src/VBox/Runtime/include/internal/dbgmod.h@ 38531

最後變更 在這個檔案從38531是 38531,由 vboxsync 提交於 14 年 前

iprt: debug info coding...

  • 屬性 svn:eol-style 設為 native
  • 屬性 svn:keywords 設為 Author Date Id Revision
檔案大小: 17.4 KB
 
1/* $Id: dbgmod.h 38531 2011-08-25 14:30:23Z vboxsync $ */
2/** @file
3 * IPRT - Internal Header for RTDbgMod and the associated interpreters.
4 */
5
6/*
7 * Copyright (C) 2008-2011 Oracle Corporation
8 *
9 * This file is part of VirtualBox Open Source Edition (OSE), as
10 * available from http://www.alldomusa.eu.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 <iprt/ldr.h> /* for PFNRTLDRENUMDBG */
33#include "internal/magics.h"
34
35RT_C_DECLS_BEGIN
36
37/** @addtogroup grp_rt_dbgmod
38 * @internal
39 * @{
40 */
41
42
43/** Pointer to the internal module structure. */
44typedef struct RTDBGMODINT *PRTDBGMODINT;
45
46/**
47 * Virtual method table for executable image interpreters.
48 */
49typedef struct RTDBGMODVTIMG
50{
51 /** Magic number (RTDBGMODVTIMG_MAGIC). */
52 uint32_t u32Magic;
53 /** Reserved. */
54 uint32_t fReserved;
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 pImgOps and pvImgPriv.
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 /**
91 * Enumerate the debug info contained in the executable image.
92 *
93 * Identical to RTLdrEnumDbgInfo.
94 *
95 * @returns IPRT status code or whatever pfnCallback returns.
96 *
97 * @param pMod Pointer to the module structure.
98 * @param pvBits Optional pointer to bits returned by
99 * RTLdrGetBits(). This can be used by some module
100 * interpreters to reduce memory consumption.
101 * @param pfnCallback The callback function. Ignore the module
102 * handle argument!
103 * @param pvUser The user argument.
104 */
105 DECLCALLBACKMEMBER(int, pfnEnumDbgInfo)(PRTDBGMODINT pMod, PFNRTLDRENUMDBG pfnCallback, void *pvUser);
106
107 /**
108 * Creates a read-only mapping of a part of the image file.
109 *
110 * @returns IPRT status code and *ppvMap set on success.
111 *
112 * @param pMod Pointer to the module structure.
113 * @param off The offset into the image file.
114 * @param cb The number of bytes to map.
115 * @param ppvMap Where to return the mapping address on success.
116 */
117 DECLCALLBACKMEMBER(int, pfnMapPart)(PRTDBGMODINT pMod, RTFOFF off, size_t cb, void const **ppvMap);
118
119 /**
120 * Unmaps memory previously mapped by pfnMapPart.
121 *
122 * @returns IPRT status code, *ppvMap set to NULL on success.
123 *
124 * @param pMod Pointer to the module structure.
125 * @param cb The size of the mapping.
126 * @param ppvMap The mapping address on input, NULL on
127 * successful return.
128 */
129 DECLCALLBACKMEMBER(int, pfnUnmapPart)(PRTDBGMODINT pMod, size_t cb, void const **ppvMap);
130
131
132 /** For catching initialization errors (RTDBGMODVTIMG_MAGIC). */
133 uint32_t u32EndMagic;
134} RTDBGMODVTIMG;
135/** Pointer to a const RTDBGMODVTIMG. */
136typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
137
138
139/**
140 * Virtual method table for debug info interpreters.
141 */
142typedef struct RTDBGMODVTDBG
143{
144 /** Magic number (RTDBGMODVTDBG_MAGIC). */
145 uint32_t u32Magic;
146 /** Mask of supported debug info types, see grp_rt_dbg_type.
147 * Used to speed up the search for a suitable interpreter. */
148 uint32_t fSupports;
149 /** The name of the interpreter. */
150 const char *pszName;
151
152 /**
153 * Try open the image.
154 *
155 * This combines probing and opening.
156 *
157 * @returns IPRT status code. No informational returns defined.
158 *
159 * @param pMod Pointer to the module that is being opened.
160 *
161 * The RTDBGMOD::pszDbgFile member will point to
162 * the filename of any debug info we're aware of
163 * on input. Also, or alternatively, it is expected
164 * that the interpreter will look for debug info in
165 * the executable image file when present and that it
166 * may ask the image interpreter for this when it's
167 * around.
168 *
169 * Upon successful return the method is expected to
170 * initialize pDbgOps and pvDbgPriv.
171 */
172 DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
173
174 /**
175 * Close the interpreter, freeing all associated resources.
176 *
177 * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
178 * to NULL upon return.
179 *
180 * @param pMod Pointer to the module structure.
181 */
182 DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
183
184
185
186 /**
187 * Converts an image relative virtual address address to a segmented address.
188 *
189 * @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
190 * @param pMod Pointer to the module structure.
191 * @param uRva The image relative address to convert.
192 * @param poffSeg Where to return the segment offset. Optional.
193 */
194 DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff)(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
195
196 /**
197 * Image size when mapped if segments are mapped adjacently.
198 *
199 * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
200 * NE and such it's a bit odder and the answer may not make much sense for them.
201 *
202 * @returns Image mapped size.
203 * @param pMod Pointer to the module structure.
204 */
205 DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize)(PRTDBGMODINT pMod);
206
207
208
209 /**
210 * Adds a segment to the module (optional).
211 *
212 * @returns IPRT status code.
213 * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
214 * @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
215 *
216 * @param pMod Pointer to the module structure.
217 * @param uRva The segment image relative address.
218 * @param cb The segment size.
219 * @param pszName The segment name.
220 * @param cchName The length of the segment name.
221 * @param fFlags Segment flags.
222 * @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
223 * The assigned segment index on successful return.
224 * Optional.
225 */
226 DECLCALLBACKMEMBER(int, pfnSegmentAdd)(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
227 uint32_t fFlags, PRTDBGSEGIDX piSeg);
228
229 /**
230 * Gets the segment count.
231 *
232 * @returns Number of segments.
233 * @retval NIL_RTDBGSEGIDX if unknown.
234 *
235 * @param pMod Pointer to the module structure.
236 */
237 DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnSegmentCount)(PRTDBGMODINT pMod);
238
239 /**
240 * Gets information about a segment.
241 *
242 * @returns IPRT status code.
243 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
244 *
245 * @param pMod Pointer to the module structure.
246 * @param iSeg The segment.
247 * @param pSegInfo Where to store the segment information.
248 */
249 DECLCALLBACKMEMBER(int, pfnSegmentByIndex)(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
250
251
252
253 /**
254 * Adds a symbol to the module (optional).
255 *
256 * @returns IPRT code.
257 * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
258 *
259 * @param pMod Pointer to the module structure.
260 * @param pszSymbol The symbol name.
261 * @param cchSymbol The length for the symbol name.
262 * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
263 * @param off The offset into the segment.
264 * @param cb The area covered by the symbol. 0 is fine.
265 * @param fFlags Flags.
266 * @param piOrdinal Where to return the symbol ordinal on success. If the
267 * interpreter doesn't do ordinals, this will be set to
268 * UINT32_MAX. Optional
269 */
270 DECLCALLBACKMEMBER(int, pfnSymbolAdd)(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol,
271 uint32_t iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags,
272 uint32_t *piOrdinal);
273
274 /**
275 * Gets the number of symbols in the module.
276 *
277 * This is used for figuring out the max value to pass to pfnSymbolByIndex among
278 * other things.
279 *
280 * @returns The number of symbols, UINT32_MAX if not known/supported.
281 *
282 * @param pMod Pointer to the module structure.
283 */
284 DECLCALLBACKMEMBER(uint32_t, pfnSymbolCount)(PRTDBGMODINT pMod);
285
286 /**
287 * Queries symbol information by ordinal number.
288 *
289 * @returns IPRT status code.
290 * @retval VINF_SUCCESS on success, no informational status code.
291 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
292 * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
293 * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at that index.
294 *
295 * @param pMod Pointer to the module structure.
296 * @param iOrdinal The symbol ordinal number.
297 * @param pSymInfo Where to store the symbol information.
298 */
299 DECLCALLBACKMEMBER(int, pfnSymbolByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
300
301 /**
302 * Queries symbol information by symbol name.
303 *
304 * @returns IPRT status code.
305 * @retval VINF_SUCCESS on success, no informational status code.
306 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
307 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
308 *
309 * @param pMod Pointer to the module structure.
310 * @param pszSymbol The symbol name.
311 * @param cchSymbol The length of the symbol name.
312 * @param pSymInfo Where to store the symbol information.
313 */
314 DECLCALLBACKMEMBER(int, pfnSymbolByName)(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol, PRTDBGSYMBOL pSymInfo);
315
316 /**
317 * Queries symbol information by address.
318 *
319 * The returned symbol is what the debug info interpreter considers the symbol
320 * most applicable to the specified address. This usually means a symbol with an
321 * address equal or lower than the requested.
322 *
323 * @returns IPRT status code.
324 * @retval VINF_SUCCESS on success, no informational status code.
325 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
326 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
327 *
328 * @param pMod Pointer to the module structure.
329 * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
330 * @param off The offset into the segment.
331 * @param poffDisp Where to store the distance between the specified address
332 * and the returned symbol. Optional.
333 * @param pSymInfo Where to store the symbol information.
334 */
335 DECLCALLBACKMEMBER(int, pfnSymbolByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
336
337
338
339 /**
340 * Adds a line number to the module (optional).
341 *
342 * @returns IPRT status code.
343 * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
344 *
345 * @param pMod Pointer to the module structure.
346 * @param pszFile The filename.
347 * @param cchFile The length of the filename.
348 * @param uLineNo The line number.
349 * @param iSeg The segment number (0-based).
350 * @param off The offset into the segment.
351 * @param piOrdinal Where to return the line number ordinal on success. If
352 * the interpreter doesn't do ordinals, this will be set to
353 * UINT32_MAX. Optional
354 */
355 DECLCALLBACKMEMBER(int, pfnLineAdd)(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
356 uint32_t iSeg, RTUINTPTR off, uint32_t *piOrdinal);
357
358 /**
359 * Gets the number of line numbers in the module.
360 *
361 * @returns The number or UINT32_MAX if not known/supported.
362 *
363 * @param pMod Pointer to the module structure.
364 */
365 DECLCALLBACKMEMBER(uint32_t, pfnLineCount)(PRTDBGMODINT pMod);
366
367 /**
368 * Queries line number information by ordinal number.
369 *
370 * @returns IPRT status code.
371 * @retval VINF_SUCCESS on success, no informational status code.
372 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
373 * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
374 * ordinal.
375 *
376 * @param pMod Pointer to the module structure.
377 * @param iOrdinal The line number ordinal number.
378 * @param pLineInfo Where to store the information about the line number.
379 */
380 DECLCALLBACKMEMBER(int, pfnLineByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
381
382 /**
383 * Queries line number information by address.
384 *
385 * @returns IPRT status code.
386 * @retval VINF_SUCCESS on success, no informational status code.
387 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
388 * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
389 *
390 * @param pMod Pointer to the module structure.
391 * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
392 * @param off The offset into the segment.
393 * @param poffDisp Where to store the distance between the specified address
394 * and the returned line number. Optional.
395 * @param pLineInfo Where to store the information about the closest line
396 * number.
397 */
398 DECLCALLBACKMEMBER(int, pfnLineByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
399
400
401 /** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
402 uint32_t u32EndMagic;
403} RTDBGMODVTDBG;
404/** Pointer to a const RTDBGMODVTDBG. */
405typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
406
407
408/**
409 * Debug module structure.
410 */
411typedef struct RTDBGMODINT
412{
413 /** Magic value (RTDBGMOD_MAGIC). */
414 uint32_t u32Magic;
415 /** The number of reference there are to this module.
416 * This is used to perform automatic cleanup and sharing. */
417 uint32_t volatile cRefs;
418 /** The module tag. */
419 uint64_t uTag;
420 /** The module name (short). */
421 char const *pszName;
422 /** The module filename. Can be NULL. */
423 char const *pszImgFile;
424 /** The debug info file (if external). Can be NULL. */
425 char const *pszDbgFile;
426
427 /** Critical section serializing access to the module. */
428 RTCRITSECT CritSect;
429
430 /** The method table for the executable image interpreter. */
431 PCRTDBGMODVTIMG pImgVt;
432 /** Pointer to the private data of the executable image interpreter. */
433 void *pvImgPriv;
434
435 /** The method table for the debug info interpreter. */
436 PCRTDBGMODVTDBG pDbgVt;
437 /** Pointer to the private data of the debug info interpreter. */
438 void *pvDbgPriv;
439
440} RTDBGMODINT;
441/** Pointer to an debug module structure. */
442typedef RTDBGMODINT *PRTDBGMODINT;
443
444
445extern DECLHIDDEN(RTSTRCACHE) g_hDbgModStrCache;
446extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDwarf;
447extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
448extern DECLHIDDEN(RTDBGMODVTIMG const) g_rtDbgModVtImgLdr;
449
450int rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
451
452/** @} */
453
454RT_C_DECLS_END
455
456#endif
457
注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

© 2025 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette