VirtualBox

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

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

IPRT: Working on debug info again.

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

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