VirtualBox

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

Last change on this file since 27432 was 26344, checked in by vboxsync, 15 years ago

Runtime: white space cleanup.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 15.7 KB
Line 
1/* $Id: dbgmod.h 26344 2010-02-09 03:39:45Z 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/** @addtogroup grp_rt_dbgmod
41 * @internal
42 * @{
43 */
44
45
46/** Pointer to the internal module structure. */
47typedef struct RTDBGMODINT *PRTDBGMODINT;
48
49/**
50 * Virtual method table for executable image interpreters.
51 */
52typedef struct RTDBGMODVTIMG
53{
54 /** Magic number (RTDBGMODVTIMG_MAGIC). */
55 uint32_t u32Magic;
56 /** Mask of supported executable image types, see grp_rt_exe_img_type.
57 * Used to speed up the search for a suitable interpreter. */
58 uint32_t fSupports;
59 /** The name of the interpreter. */
60 const char *pszName;
61
62 /**
63 * Try open the image.
64 *
65 * This combines probing and opening.
66 *
67 * @returns IPRT status code. No informational returns defined.
68 *
69 * @param pMod Pointer to the module that is being opened.
70 *
71 * The RTDBGMOD::pszDbgFile member will point to
72 * the filename of any debug info we're aware of
73 * on input. Also, or alternatively, it is expected
74 * that the interpreter will look for debug info in
75 * the executable image file when present and that it
76 * may ask the image interpreter for this when it's
77 * around.
78 *
79 * Upon successful return the method is expected to
80 * initialize pDbgOps and pvDbgPriv.
81 */
82 DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
83
84 /**
85 * Close the interpreter, freeing all associated resources.
86 *
87 * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
88 * to NULL upon return.
89 *
90 * @param pMod Pointer to the module structure.
91 */
92 DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
93
94} RTDBGMODVTIMG;
95/** Pointer to a const RTDBGMODVTIMG. */
96typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
97
98
99/**
100 * Virtual method table for debug info interpreters.
101 */
102typedef struct RTDBGMODVTDBG
103{
104 /** Magic number (RTDBGMODVTDBG_MAGIC). */
105 uint32_t u32Magic;
106 /** Mask of supported debug info types, see grp_rt_dbg_type.
107 * Used to speed up the search for a suitable interpreter. */
108 uint32_t fSupports;
109 /** The name of the interpreter. */
110 const char *pszName;
111
112 /**
113 * Try open the image.
114 *
115 * This combines probing and opening.
116 *
117 * @returns IPRT status code. No informational returns defined.
118 *
119 * @param pMod Pointer to the module that is being opened.
120 *
121 * The RTDBGMOD::pszDbgFile member will point to
122 * the filename of any debug info we're aware of
123 * on input. Also, or alternatively, it is expected
124 * that the interpreter will look for debug info in
125 * the executable image file when present and that it
126 * may ask the image interpreter for this when it's
127 * around.
128 *
129 * Upon successful return the method is expected to
130 * initialize pDbgOps and pvDbgPriv.
131 */
132 DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
133
134 /**
135 * Close the interpreter, freeing all associated resources.
136 *
137 * The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
138 * to NULL upon return.
139 *
140 * @param pMod Pointer to the module structure.
141 */
142 DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
143
144
145
146 /**
147 * Converts an image relative virtual address address to a segmented address.
148 *
149 * @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
150 * @param pMod Pointer to the module structure.
151 * @param uRva The image relative address to convert.
152 * @param poffSeg Where to return the segment offset. Optional.
153 */
154 DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff)(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
155
156 /**
157 * Image size when mapped if segments are mapped adjecently.
158 *
159 * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
160 * NE and such it's a bit odder and the answer may not make much sense for them.
161 *
162 * @returns Image mapped size.
163 * @param pMod Pointer to the module structure.
164 */
165 DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize)(PRTDBGMODINT pMod);
166
167
168
169 /**
170 * Adds a segment to the module (optional).
171 *
172 * @returns IPRT status code.
173 * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
174 * @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
175 *
176 * @param pMod Pointer to the module structure.
177 * @param uRva The segment image relative address.
178 * @param cb The segment size.
179 * @param pszName The segment name.
180 * @param cchName The length of the segment name.
181 * @param fFlags Segment flags.
182 * @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
183 * The assigned segment index on successful return.
184 * Optional.
185 */
186 DECLCALLBACKMEMBER(int, pfnSegmentAdd)(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
187 uint32_t fFlags, PRTDBGSEGIDX piSeg);
188
189 /**
190 * Gets the segment count.
191 *
192 * @returns Number of segments.
193 * @retval NIL_RTDBGSEGIDX if unknown.
194 *
195 * @param pMod Pointer to the module structure.
196 */
197 DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnSegmentCount)(PRTDBGMODINT pMod);
198
199 /**
200 * Gets information about a segment.
201 *
202 * @returns IPRT status code.
203 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
204 *
205 * @param pMod Pointer to the module structure.
206 * @param iSeg The segment.
207 * @param pSegInfo Where to store the segment information.
208 */
209 DECLCALLBACKMEMBER(int, pfnSegmentByIndex)(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
210
211
212
213 /**
214 * Adds a symbol to the module (optional).
215 *
216 * @returns IPRT code.
217 * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
218 *
219 * @param pMod Pointer to the module structure.
220 * @param pszSymbol The symbol name.
221 * @param cchSymbol The length for the symbol name.
222 * @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
223 * @param off The offset into the segment.
224 * @param cb The area covered by the symbol. 0 is fine.
225 * @param fFlags Flags.
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 uLineNo The line number.
309 * @param iSeg The segment number (0-based).
310 * @param off The offset into the segment.
311 * @param piOrdinal Where to return the line number ordinal on success. If
312 * the interpreter doesn't do ordinals, this will be set to
313 * UINT32_MAX. Optional
314 */
315 DECLCALLBACKMEMBER(int, pfnLineAdd)(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
316 uint32_t iSeg, RTUINTPTR off, uint32_t *piOrdinal);
317
318 /**
319 * Gets the number of line numbers in the module.
320 *
321 * @returns The number or UINT32_MAX if not known/supported.
322 *
323 * @param pMod Pointer to the module structure.
324 */
325 DECLCALLBACKMEMBER(uint32_t, pfnLineCount)(PRTDBGMODINT pMod);
326
327 /**
328 * Queries line number information by ordinal number.
329 *
330 * @returns IPRT status code.
331 * @retval VINF_SUCCESS on success, no informational status code.
332 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
333 * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
334 * ordinal.
335 *
336 * @param pMod Pointer to the module structure.
337 * @param iOrdinal The line number ordinal number.
338 * @param pLineInfo Where to store the information about the line number.
339 */
340 DECLCALLBACKMEMBER(int, pfnLineByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
341
342 /**
343 * Queries line number information by address.
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 no suitable line number was found.
349 *
350 * @param pMod Pointer to the module structure.
351 * @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
352 * @param off The offset into the segment.
353 * @param poffDisp Where to store the distance between the specified address
354 * and the returned line number. Optional.
355 * @param pLineInfo Where to store the information about the closest line
356 * number.
357 */
358 DECLCALLBACKMEMBER(int, pfnLineByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
359
360
361 /** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
362 uint32_t u32EndMagic;
363} RTDBGMODVTDBG;
364/** Pointer to a const RTDBGMODVTDBG. */
365typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
366
367
368/**
369 * Debug module structure.
370 */
371typedef struct RTDBGMODINT
372{
373 /** Magic value (RTDBGMOD_MAGIC). */
374 uint32_t u32Magic;
375 /** The number of reference there are to this module.
376 * This is used to perform automatic cleanup and sharing. */
377 uint32_t volatile cRefs;
378 /** The module tag. */
379 uint64_t uTag;
380 /** The module name (short). */
381 char const *pszName;
382 /** The module filename. Can be NULL. */
383 char const *pszImgFile;
384 /** The debug info file (if external). Can be NULL. */
385 char const *pszDbgFile;
386
387 /** Critical section serializing access to the module. */
388 RTCRITSECT CritSect;
389
390 /** The method table for the executable image interpreter. */
391 PCRTDBGMODVTIMG pImgVt;
392 /** Pointer to the private data of the executable image interpreter. */
393 void *pvImgPriv;
394
395 /** The method table for the debug info interpreter. */
396 PCRTDBGMODVTDBG pDbgVt;
397 /** Pointer to the private data of the debug info interpreter. */
398 void *pvDbgPriv;
399
400} RTDBGMODINT;
401/** Pointer to an debug module structure. */
402typedef RTDBGMODINT *PRTDBGMODINT;
403
404
405extern DECLHIDDEN(RTSTRCACHE) g_hDbgModStrCache;
406extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
407
408int rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
409
410/** @} */
411
412RT_C_DECLS_END
413
414#endif
415
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