VirtualBox

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

Last change on this file since 21041 was 20801, checked in by vboxsync, 16 years ago

IPRT: The rest of the basic RTDbgMod code.

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