VirtualBox

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

Last change on this file since 32131 was 28800, checked in by vboxsync, 15 years ago

Automated rebranding to Oracle copyright/license strings via filemuncher

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.5 KB
Line 
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
34RT_C_DECLS_BEGIN
35
36/** @addtogroup grp_rt_dbgmod
37 * @internal
38 * @{
39 */
40
41
42/** Pointer to the internal module structure. */
43typedef struct RTDBGMODINT *PRTDBGMODINT;
44
45/**
46 * Virtual method table for executable image interpreters.
47 */
48typedef 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. */
92typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
93
94
95/**
96 * Virtual method table for debug info interpreters.
97 */
98typedef 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. */
361typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
362
363
364/**
365 * Debug module structure.
366 */
367typedef 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. */
398typedef RTDBGMODINT *PRTDBGMODINT;
399
400
401extern DECLHIDDEN(RTSTRCACHE) g_hDbgModStrCache;
402extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
403
404int rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
405
406/** @} */
407
408RT_C_DECLS_END
409
410#endif
411
Note: See TracBrowser for help on using the repository browser.

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