dbgmod.h@ 46048

Last change on this file since 46048 was 46048, checked in by vboxsync, 12 years ago
Added a RTDbgMod reader that employs DbgHelp.dll.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 21.5 KB

Line
1	/* $Id: dbgmod.h 46048 2013-05-14 07:44:30Z vboxsync $ */
2	/** @file
3	* IPRT - Internal Header for RTDbgMod and the associated interpreters.
4	*/
5
6	/*
7	* Copyright (C) 2008-2012 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 <iprt/ldr.h> /* for PFNRTLDRENUMDBG */
33	#include "internal/magics.h"
34
35	RT_C_DECLS_BEGIN
36
37	/** @addtogroup grp_rt_dbgmod
38	* @internal
39	* @{
40	*/
41
42
43	/** Pointer to the internal module structure. */
44	typedef struct RTDBGMODINT *PRTDBGMODINT;
45
46	/**
47	* Virtual method table for executable image interpreters.
48	*/
49	typedef 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 pfnCallback The callback function. Ignore the module
99	* handle argument!
100	* @param pvUser The user argument.
101	*/
102	DECLCALLBACKMEMBER(int, pfnEnumDbgInfo)(PRTDBGMODINT pMod, PFNRTLDRENUMDBG pfnCallback, void *pvUser);
103
104	/**
105	* Enumerate the segments in the executable image.
106	*
107	* Identical to RTLdrEnumSegments.
108	*
109	* @returns IPRT status code or whatever pfnCallback returns.
110	*
111	* @param pMod Pointer to the module structure.
112	* @param pfnCallback The callback function. Ignore the module
113	* handle argument!
114	* @param pvUser The user argument.
115	*/
116	DECLCALLBACKMEMBER(int, pfnEnumSegments)(PRTDBGMODINT pMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser);
117
118	/**
119	* Gets the size of the loaded image.
120	*
121	* Identical to RTLdrSize.
122	*
123	* @returns The size in bytes, RTUINTPTR_MAX on failure.
124	*
125	* @param pMod Pointer to the module structure.
126	*/
127	DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize)(PRTDBGMODINT pMod);
128
129	/**
130	* Converts a link address to a segment:offset address (RVA included).
131	*
132	* @returns IPRT status code.
133	*
134	* @param pMod Pointer to the module structure.
135	* @param LinkAddress The link address to convert.
136	* @param piSeg The segment index.
137	* @param poffSeg Where to return the segment offset.
138	*/
139	DECLCALLBACKMEMBER(int, pfnLinkAddressToSegOffset)(PRTDBGMODINT pMod, RTLDRADDR LinkAddress,
140	PRTDBGSEGIDX piSeg, PRTLDRADDR poffSeg);
141
142	/**
143	* Creates a read-only mapping of a part of the image file.
144	*
145	* @returns IPRT status code and *ppvMap set on success.
146	*
147	* @param pMod Pointer to the module structure.
148	* @param off The offset into the image file.
149	* @param cb The number of bytes to map.
150	* @param ppvMap Where to return the mapping address on success.
151	*/
152	DECLCALLBACKMEMBER(int, pfnMapPart)(PRTDBGMODINT pMod, RTFOFF off, size_t cb, void const **ppvMap);
153
154	/**
155	* Unmaps memory previously mapped by pfnMapPart.
156	*
157	* @returns IPRT status code, *ppvMap set to NULL on success.
158	*
159	* @param pMod Pointer to the module structure.
160	* @param cb The size of the mapping.
161	* @param ppvMap The mapping address on input, NULL on
162	* successful return.
163	*/
164	DECLCALLBACKMEMBER(int, pfnUnmapPart)(PRTDBGMODINT pMod, size_t cb, void const **ppvMap);
165
166
167	/** For catching initialization errors (RTDBGMODVTIMG_MAGIC). */
168	uint32_t u32EndMagic;
169	} RTDBGMODVTIMG;
170	/** Pointer to a const RTDBGMODVTIMG. */
171	typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
172
173
174	/**
175	* Virtual method table for debug info interpreters.
176	*/
177	typedef struct RTDBGMODVTDBG
178	{
179	/** Magic number (RTDBGMODVTDBG_MAGIC). */
180	uint32_t u32Magic;
181	/** Mask of supported debug info types, see grp_rt_dbg_type.
182	* Used to speed up the search for a suitable interpreter. */
183	uint32_t fSupports;
184	/** The name of the interpreter. */
185	const char *pszName;
186
187	/**
188	* Try open the image.
189	*
190	* This combines probing and opening.
191	*
192	* @returns IPRT status code. No informational returns defined.
193	*
194	* @param pMod Pointer to the module that is being opened.
195	*
196	* The RTDBGMOD::pszDbgFile member will point to
197	* the filename of any debug info we're aware of
198	* on input. Also, or alternatively, it is expected
199	* that the interpreter will look for debug info in
200	* the executable image file when present and that it
201	* may ask the image interpreter for this when it's
202	* around.
203	*
204	* Upon successful return the method is expected to
205	* initialize pDbgOps and pvDbgPriv.
206	*/
207	DECLCALLBACKMEMBER(int, pfnTryOpen)(PRTDBGMODINT pMod);
208
209	/**
210	* Close the interpreter, freeing all associated resources.
211	*
212	* The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
213	* to NULL upon return.
214	*
215	* @param pMod Pointer to the module structure.
216	*/
217	DECLCALLBACKMEMBER(int, pfnClose)(PRTDBGMODINT pMod);
218
219
220
221	/**
222	* Converts an image relative virtual address address to a segmented address.
223	*
224	* @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
225	* @param pMod Pointer to the module structure.
226	* @param uRva The image relative address to convert.
227	* @param poffSeg Where to return the segment offset. Optional.
228	*/
229	DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff)(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
230
231	/**
232	* Image size when mapped if segments are mapped adjacently.
233	*
234	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
235	* NE and such it's a bit odder and the answer may not make much sense for them.
236	*
237	* @returns Image mapped size.
238	* @param pMod Pointer to the module structure.
239	*/
240	DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize)(PRTDBGMODINT pMod);
241
242
243
244	/**
245	* Adds a segment to the module (optional).
246	*
247	* @returns IPRT status code.
248	* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
249	* @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
250	*
251	* @param pMod Pointer to the module structure.
252	* @param uRva The segment image relative address.
253	* @param cb The segment size.
254	* @param pszName The segment name.
255	* @param cchName The length of the segment name.
256	* @param fFlags Segment flags.
257	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
258	* The assigned segment index on successful return.
259	* Optional.
260	*/
261	DECLCALLBACKMEMBER(int, pfnSegmentAdd)(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
262	uint32_t fFlags, PRTDBGSEGIDX piSeg);
263
264	/**
265	* Gets the segment count.
266	*
267	* @returns Number of segments.
268	* @retval NIL_RTDBGSEGIDX if unknown.
269	*
270	* @param pMod Pointer to the module structure.
271	*/
272	DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnSegmentCount)(PRTDBGMODINT pMod);
273
274	/**
275	* Gets information about a segment.
276	*
277	* @returns IPRT status code.
278	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
279	*
280	* @param pMod Pointer to the module structure.
281	* @param iSeg The segment.
282	* @param pSegInfo Where to store the segment information.
283	*/
284	DECLCALLBACKMEMBER(int, pfnSegmentByIndex)(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
285
286
287
288	/**
289	* Adds a symbol to the module (optional).
290	*
291	* @returns IPRT code.
292	* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
293	*
294	* @param pMod Pointer to the module structure.
295	* @param pszSymbol The symbol name.
296	* @param cchSymbol The length for the symbol name.
297	* @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
298	* @param off The offset into the segment.
299	* @param cb The area covered by the symbol. 0 is fine.
300	* @param fFlags Flags.
301	* @param piOrdinal Where to return the symbol ordinal on success. If the
302	* interpreter doesn't do ordinals, this will be set to
303	* UINT32_MAX. Optional
304	*/
305	DECLCALLBACKMEMBER(int, pfnSymbolAdd)(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol,
306	uint32_t iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags,
307	uint32_t *piOrdinal);
308
309	/**
310	* Gets the number of symbols in the module.
311	*
312	* This is used for figuring out the max value to pass to pfnSymbolByIndex among
313	* other things.
314	*
315	* @returns The number of symbols, UINT32_MAX if not known/supported.
316	*
317	* @param pMod Pointer to the module structure.
318	*/
319	DECLCALLBACKMEMBER(uint32_t, pfnSymbolCount)(PRTDBGMODINT pMod);
320
321	/**
322	* Queries symbol information by ordinal number.
323	*
324	* @returns IPRT status code.
325	* @retval VINF_SUCCESS on success, no informational status code.
326	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
327	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
328	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at that index.
329	*
330	* @param pMod Pointer to the module structure.
331	* @param iOrdinal The symbol ordinal number.
332	* @param pSymInfo Where to store the symbol information.
333	*/
334	DECLCALLBACKMEMBER(int, pfnSymbolByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
335
336	/**
337	* Queries symbol information by symbol name.
338	*
339	* @returns IPRT status code.
340	* @retval VINF_SUCCESS on success, no informational status code.
341	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
342	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
343	*
344	* @param pMod Pointer to the module structure.
345	* @param pszSymbol The symbol name.
346	* @param cchSymbol The length of the symbol name.
347	* @param pSymInfo Where to store the symbol information.
348	*/
349	DECLCALLBACKMEMBER(int, pfnSymbolByName)(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol, PRTDBGSYMBOL pSymInfo);
350
351	/**
352	* Queries symbol information by address.
353	*
354	* The returned symbol is what the debug info interpreter considers the symbol
355	* most applicable to the specified address. This usually means a symbol with an
356	* address equal or lower than the requested.
357	*
358	* @returns IPRT status code.
359	* @retval VINF_SUCCESS on success, no informational status code.
360	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
361	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
362	*
363	* @param pMod Pointer to the module structure.
364	* @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
365	* @param off The offset into the segment.
366	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
367	* @param poffDisp Where to store the distance between the specified address
368	* and the returned symbol. Optional.
369	* @param pSymInfo Where to store the symbol information.
370	*/
371	DECLCALLBACKMEMBER(int, pfnSymbolByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, uint32_t fFlags,
372	PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
373
374
375
376	/**
377	* Adds a line number to the module (optional).
378	*
379	* @returns IPRT status code.
380	* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
381	*
382	* @param pMod Pointer to the module structure.
383	* @param pszFile The filename.
384	* @param cchFile The length of the filename.
385	* @param uLineNo The line number.
386	* @param iSeg The segment number (0-based).
387	* @param off The offset into the segment.
388	* @param piOrdinal Where to return the line number ordinal on success. If
389	* the interpreter doesn't do ordinals, this will be set to
390	* UINT32_MAX. Optional
391	*/
392	DECLCALLBACKMEMBER(int, pfnLineAdd)(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
393	uint32_t iSeg, RTUINTPTR off, uint32_t *piOrdinal);
394
395	/**
396	* Gets the number of line numbers in the module.
397	*
398	* @returns The number or UINT32_MAX if not known/supported.
399	*
400	* @param pMod Pointer to the module structure.
401	*/
402	DECLCALLBACKMEMBER(uint32_t, pfnLineCount)(PRTDBGMODINT pMod);
403
404	/**
405	* Queries line number information by ordinal number.
406	*
407	* @returns IPRT status code.
408	* @retval VINF_SUCCESS on success, no informational status code.
409	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
410	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
411	* ordinal.
412	*
413	* @param pMod Pointer to the module structure.
414	* @param iOrdinal The line number ordinal number.
415	* @param pLineInfo Where to store the information about the line number.
416	*/
417	DECLCALLBACKMEMBER(int, pfnLineByOrdinal)(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
418
419	/**
420	* Queries line number information by address.
421	*
422	* @returns IPRT status code.
423	* @retval VINF_SUCCESS on success, no informational status code.
424	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
425	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
426	*
427	* @param pMod Pointer to the module structure.
428	* @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
429	* @param off The offset into the segment.
430	* @param poffDisp Where to store the distance between the specified address
431	* and the returned line number. Optional.
432	* @param pLineInfo Where to store the information about the closest line
433	* number.
434	*/
435	DECLCALLBACKMEMBER(int, pfnLineByAddr)(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
436
437
438	/** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
439	uint32_t u32EndMagic;
440	} RTDBGMODVTDBG;
441	/** Pointer to a const RTDBGMODVTDBG. */
442	typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
443
444
445	/**
446	* Deferred loading callback.
447	*
448	* @returns IPRT status code. On success the necessary method tables should be
449	* installed in @a pMod.
450	* @param pMod Pointer to the debug module structure.
451	* @param pDeferred The deferred load data.
452	*/
453	typedef DECLCALLBACK(int) FNRTDBGMODDEFERRED(PRTDBGMODINT pMod, struct RTDBGMODDEFERRED *pDeferred);
454	/** Pointer to a deferred loading callback. */
455	typedef FNRTDBGMODDEFERRED *PFNRTDBGMODDEFERRED;
456
457
458	/**
459	* Structure pointed to by pvDbgPriv and/or pvImgPriv when
460	* g_rtDbgModVtDbgDeferred and/or g_rtDbgModVtImgDeferred are being used.
461	*/
462	typedef struct RTDBGMODDEFERRED
463	{
464	/** The image size.
465	* Deferred loading is almost pointless without knowing the module size, as
466	* it cannot be mapped (correctly) without it. */
467	RTUINTPTR cbImage;
468	/** Reference counter. */
469	uint32_t volatile cRefs;
470	/** The configuration instance (referenced), can be NIL. */
471	RTDBGCFG hDbgCfg;
472	/** Performs deferred loading of the module. */
473	PFNRTDBGMODDEFERRED pfnDeferred;
474	/** Callback specific data. */
475	union
476	{
477	struct
478	{
479	/** The time/date stamp of the executable image and codeview file. */
480	uint32_t uTimestamp;
481	} PeImage,
482	OldCodeView;
483
484	struct
485	{
486	/** The PDB uuid. */
487	RTUUID Uuid;
488	/** The PDB age. */
489	uint32_t uAge;
490	} NewCodeview;
491
492	struct
493	{
494	/** The CRC-32 value found in the .gnu_debuglink section. */
495	uint32_t uCrc32;
496	} GnuDebugLink;
497	} u;
498	} RTDBGMODDEFERRED;
499	/** Pointer to the deferred loading data. */
500	typedef RTDBGMODDEFERRED *PRTDBGMODDEFERRED;
501
502
503	/**
504	* Debug module structure.
505	*/
506	typedef struct RTDBGMODINT
507	{
508	/** Magic value (RTDBGMOD_MAGIC). */
509	uint32_t u32Magic;
510	/** The number of reference there are to this module.
511	* This is used to perform automatic cleanup and sharing. */
512	uint32_t volatile cRefs;
513	/** The module tag. */
514	uint64_t uTag;
515
516	/** When set, the loading of the image and debug info (including locating any
517	* external files), will not have taken place yet. */
518	uint32_t fDeferred : 1;
519	/** Set if deferred loading failed. */
520	uint32_t fDeferredFailed : 1;
521	/** Set if the debug info is based on image exports and segments. */
522	uint32_t fExports : 1;
523	/** Alignment padding. */
524	uint32_t fPadding1 : 29;
525	#if ARCH_BITS == 64
526	uint32_t u32Padding2;
527	#endif
528
529	/** The module name (short). */
530	char const *pszName;
531	/** The module filename. Can be NULL. */
532	char const *pszImgFile;
533	/** The debug info file (if external). Can be NULL. */
534	char const *pszDbgFile;
535
536	/** The method table for the executable image interpreter. */
537	PCRTDBGMODVTIMG pImgVt;
538	/** Pointer to the private data of the executable image interpreter. */
539	void *pvImgPriv;
540
541	/** The method table for the debug info interpreter. */
542	PCRTDBGMODVTDBG pDbgVt;
543	/** Pointer to the private data of the debug info interpreter. */
544	void *pvDbgPriv;
545
546	/** Critical section serializing access to the module. */
547	RTCRITSECT CritSect;
548	} RTDBGMODINT;
549	/** Pointer to an debug module structure. */
550	typedef RTDBGMODINT *PRTDBGMODINT;
551
552
553	extern DECLHIDDEN(RTSTRCACHE) g_hDbgModStrCache;
554	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDwarf;
555	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
556	#ifdef RT_OS_WINDOWS
557	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDbgHelp;
558	#endif
559	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDeferred;
560
561	extern DECLHIDDEN(RTDBGMODVTIMG const) g_rtDbgModVtImgLdr;
562	extern DECLHIDDEN(RTDBGMODVTIMG const) g_rtDbgModVtImgDeferred;
563
564	DECLHIDDEN(int) rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
565	DECLHIDDEN(int) rtDbgModCreateForExports(PRTDBGMODINT pDbgMod);
566	DECLHIDDEN(int) rtDbgModDeferredCreate(PRTDBGMODINT pDbgMod, PFNRTDBGMODDEFERRED pfnDeferred, RTUINTPTR cbImage,
567	RTDBGCFG hDbgCfg, PRTDBGMODDEFERRED *ppDeferred);
568
569	/** @} */
570
571	RT_C_DECLS_END
572
573	#endif
574

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: