dbgmod.h@ 85121

Last change on this file since 85121 was 85121, checked in by vboxsync, 4 years ago
iprt/cdefs.h: Refactored the typedef use of DECLCALLBACK as well as DECLCALLBACKMEMBER to wrap the whole expression, similar to the DECLR?CALLBACKMEMBER macros. This allows adding a throw() at the end when compiling with the VC++ compiler to indicate that the callbacks won't throw anything, so we can stop supressing the C5039 warning about passing functions that can potential throw C++ exceptions to extern C code that can't necessarily cope with such (unwind,++). Introduced a few _EX variations that allows specifying different/no calling convention too, as that's handy when dynamically resolving host APIs. Fixed numerous places missing DECLCALLBACK and such. Left two angry @todos regarding use of CreateThread. bugref:9794
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.6 KB

Line
1	/* $Id: dbgmod.h 85121 2020-07-08 19:33:26Z vboxsync $ */
2	/** @file
3	* IPRT - Internal Header for RTDbgMod and the associated interpreters.
4	*/
5
6	/*
7	* Copyright (C) 2008-2020 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 IPRT_INCLUDED_INTERNAL_dbgmod_h
28	#define IPRT_INCLUDED_INTERNAL_dbgmod_h
29	#ifndef RT_WITHOUT_PRAGMA_ONCE
30	# pragma once
31	#endif
32
33	#include <iprt/types.h>
34	#include <iprt/critsect.h>
35	#include <iprt/ldr.h> /* for PFNRTLDRENUMDBG */
36	#include "internal/magics.h"
37
38	RT_C_DECLS_BEGIN
39
40	/** @addtogroup grp_rt_dbgmod
41	* @internal
42	* @{
43	*/
44
45
46	/** Pointer to the internal module structure. */
47	typedef struct RTDBGMODINT *PRTDBGMODINT;
48
49	/**
50	* Virtual method table for executable image interpreters.
51	*/
52	typedef struct RTDBGMODVTIMG
53	{
54	/** Magic number (RTDBGMODVTIMG_MAGIC). */
55	uint32_t u32Magic;
56	/** Reserved. */
57	uint32_t fReserved;
58	/** The name of the interpreter. */
59	const char *pszName;
60
61	/**
62	* Try open the image.
63	*
64	* This combines probing and opening.
65	*
66	* @returns IPRT status code. No informational returns defined.
67	*
68	* @param pMod Pointer to the module that is being opened.
69	*
70	* The RTDBGMOD::pszDbgFile member will point to
71	* the filename of any debug info we're aware of
72	* on input. Also, or alternatively, it is expected
73	* that the interpreter will look for debug info in
74	* the executable image file when present and that it
75	* may ask the image interpreter for this when it's
76	* around.
77	*
78	* Upon successful return the method is expected to
79	* initialize pImgOps and pvImgPriv.
80	* @param enmArch The desired architecture.
81	* @param fLdrFlags Extra loader flags (RTLDR_O_XXX).
82	*/
83	DECLCALLBACKMEMBER(int, pfnTryOpen,(PRTDBGMODINT pMod, RTLDRARCH enmArch, uint32_t fLdrFlags));
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	/**
96	* Enumerate the debug info contained in the executable image.
97	*
98	* Identical to RTLdrEnumDbgInfo.
99	*
100	* @returns IPRT status code or whatever pfnCallback returns.
101	*
102	* @param pMod Pointer to the module structure.
103	* @param pfnCallback The callback function. Ignore the module
104	* handle argument!
105	* @param pvUser The user argument.
106	*/
107	DECLCALLBACKMEMBER(int, pfnEnumDbgInfo,(PRTDBGMODINT pMod, PFNRTLDRENUMDBG pfnCallback, void *pvUser));
108
109	/**
110	* Enumerate the segments in the executable image.
111	*
112	* Identical to RTLdrEnumSegments.
113	*
114	* @returns IPRT status code or whatever pfnCallback returns.
115	*
116	* @param pMod Pointer to the module structure.
117	* @param pfnCallback The callback function. Ignore the module
118	* handle argument!
119	* @param pvUser The user argument.
120	*/
121	DECLCALLBACKMEMBER(int, pfnEnumSegments,(PRTDBGMODINT pMod, PFNRTLDRENUMSEGS pfnCallback, void *pvUser));
122
123	/**
124	* Enumerates the symbols exported by the module.
125	*
126	* @returns iprt status code, which might have been returned by pfnCallback.
127	* @param pMod Pointer to the module structure.
128	* @param fFlags Flags indicating what to return and such.
129	* @param BaseAddress The image base addressto use when calculating the
130	* symbol values.
131	* @param pfnCallback The callback function which each symbol is to be fed
132	* to.
133	* @param pvUser User argument to pass to the enumerator.
134	*/
135	DECLCALLBACKMEMBER(int, pfnEnumSymbols,(PRTDBGMODINT pMod, uint32_t fFlags, RTLDRADDR BaseAddress,
136	PFNRTLDRENUMSYMS pfnCallback, void *pvUser));
137
138	/**
139	* Gets the size of the loaded image.
140	*
141	* Identical to RTLdrSize.
142	*
143	* @returns The size in bytes, RTUINTPTR_MAX on failure.
144	*
145	* @param pMod Pointer to the module structure.
146	*/
147	DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize,(PRTDBGMODINT pMod));
148
149	/**
150	* Converts a link address to a segment:offset address (RVA included).
151	*
152	* @returns IPRT status code.
153	*
154	* @param pMod Pointer to the module structure.
155	* @param LinkAddress The link address to convert.
156	* @param piSeg The segment index.
157	* @param poffSeg Where to return the segment offset.
158	*/
159	DECLCALLBACKMEMBER(int, pfnLinkAddressToSegOffset,(PRTDBGMODINT pMod, RTLDRADDR LinkAddress,
160	PRTDBGSEGIDX piSeg, PRTLDRADDR poffSeg));
161
162	/**
163	* Converts an image relative virtual address to a segment:offset.
164	*
165	* @returns IPRT status code.
166	*
167	* @param pMod Pointer to the loader module structure.
168	* @param Rva The RVA to convert.
169	* @param piSeg The segment index.
170	* @param poffSeg Where to return the segment offset.
171	*/
172	DECLCALLBACKMEMBER(int, pfnRvaToSegOffset,(PRTDBGMODINT pMod, RTLDRADDR Rva, uint32_t *piSeg, PRTLDRADDR poffSeg));
173
174	/**
175	* Creates a read-only mapping of a part of the image file.
176	*
177	* @returns IPRT status code and *ppvMap set on success.
178	*
179	* @param pMod Pointer to the module structure.
180	* @param iDbgInfo The debug info ordinal number if the request
181	* corresponds exactly to a debug info part from
182	* pfnEnumDbgInfo. Otherwise, pass UINT32_MAX.
183	* @param off The offset into the image file.
184	* @param cb The number of bytes to map.
185	* @param ppvMap Where to return the mapping address on success.
186	*
187	* @remarks Fixups will only be applied if @a iDbgInfo is specified.
188	*/
189	DECLCALLBACKMEMBER(int, pfnMapPart,(PRTDBGMODINT pMod, uint32_t iDbgInfo, RTFOFF off, size_t cb, void const **ppvMap));
190
191	/**
192	* Unmaps memory previously mapped by pfnMapPart.
193	*
194	* @returns IPRT status code, *ppvMap set to NULL on success.
195	*
196	* @param pMod Pointer to the module structure.
197	* @param cb The size of the mapping.
198	* @param ppvMap The mapping address on input, NULL on
199	* successful return.
200	*/
201	DECLCALLBACKMEMBER(int, pfnUnmapPart,(PRTDBGMODINT pMod, size_t cb, void const **ppvMap));
202
203	/**
204	* Reads data from the image file.
205	*
206	* @returns IPRT status code, *ppvMap set to NULL on success.
207	*
208	* @param pMod Pointer to the module structure.
209	* @param iDbgInfoHint The debug info ordinal number hint, pass UINT32_MAX
210	* if not know or sure.
211	* @param off The offset into the image file.
212	* @param pvBuf The buffer to read into.
213	* @param cb The number of bytes to read.
214	*/
215	DECLCALLBACKMEMBER(int, pfnReadAt,(PRTDBGMODINT pMod, uint32_t iDbgInfoHint, RTFOFF off, void *pvBuf, size_t cb));
216
217	/**
218	* Gets the image format.
219	*
220	* @returns Valid image format on success, RTLDRFMT_INVALID if not supported.
221	* @param pMod Pointer to the module structure.
222	*/
223	DECLCALLBACKMEMBER(RTLDRFMT, pfnGetFormat,(PRTDBGMODINT pMod));
224
225	/**
226	* Gets the image architecture.
227	*
228	* @returns Valid image architecutre on success, RTLDRARCH_WHATEVER if not
229	* supported.
230	* @param pMod Pointer to the module structure.
231	*/
232	DECLCALLBACKMEMBER(RTLDRARCH, pfnGetArch,(PRTDBGMODINT pMod));
233
234	/**
235	* Generic method for querying image properties.
236	*
237	* @returns IPRT status code.
238	* @param pMod Pointer to the module structure.
239	* @param enmProp The property to query.
240	* @param pvBuf Pointer to the return buffer.
241	* @param cbBuf The size of the return buffer.
242	* @param pcbRet How many bytes was actually returned. In the
243	* case of VERR_BUFFER_OVERFLOW this will contain
244	* the required buffer size. Optional.
245	* @sa RTLdrQueryPropEx
246	*/
247	DECLCALLBACKMEMBER(int, pfnQueryProp,(PRTDBGMODINT pMod, RTLDRPROP enmProp, void pvBuf, size_t cbBuf, size_t pcbRet));
248
249	/**
250	* Try use unwind information to unwind one frame.
251	*
252	* @returns IPRT status code. Last informational status from stack reader callback.
253	* @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
254	* @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
255	* for the location given by iSeg:off.
256	*
257	* @param pMod Pointer to the module structure.
258	* @param iSeg The segment number of the program counter.
259	* @param off The offset into @a iSeg. Together with @a iSeg
260	* this corresponds to the RTDBGUNWINDSTATE::uPc
261	* value pointed to by @a pState.
262	* @param pState The unwind state to work.
263	*
264	* @sa RTLdrUnwindFrame, RTDbgModUnwindFrame
265	*/
266	DECLCALLBACKMEMBER(int, pfnUnwindFrame,(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTDBGUNWINDSTATE pState));
267
268	/** For catching initialization errors (RTDBGMODVTIMG_MAGIC). */
269	uint32_t u32EndMagic;
270	} RTDBGMODVTIMG;
271	/** Pointer to a const RTDBGMODVTIMG. */
272	typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
273
274
275	/**
276	* Virtual method table for debug info interpreters.
277	*/
278	typedef struct RTDBGMODVTDBG
279	{
280	/** Magic number (RTDBGMODVTDBG_MAGIC). */
281	uint32_t u32Magic;
282	/** Mask of supported debug info types, see grp_rt_dbg_type.
283	* Used to speed up the search for a suitable interpreter. */
284	uint32_t fSupports;
285	/** The name of the interpreter. */
286	const char *pszName;
287
288	/**
289	* Try open the image.
290	*
291	* This combines probing and opening.
292	*
293	* @returns IPRT status code. No informational returns defined.
294	*
295	* @param pMod Pointer to the module that is being opened.
296	*
297	* The RTDBGMOD::pszDbgFile member will point to
298	* the filename of any debug info we're aware of
299	* on input. Also, or alternatively, it is expected
300	* that the interpreter will look for debug info in
301	* the executable image file when present and that it
302	* may ask the image interpreter for this when it's
303	* around.
304	*
305	* Upon successful return the method is expected to
306	* initialize pDbgOps and pvDbgPriv.
307	* @param enmArch The desired architecture.
308	*/
309	DECLCALLBACKMEMBER(int, pfnTryOpen,(PRTDBGMODINT pMod, RTLDRARCH enmArch));
310
311	/**
312	* Close the interpreter, freeing all associated resources.
313	*
314	* The caller sets the pDbgOps and pvDbgPriv RTDBGMOD members
315	* to NULL upon return.
316	*
317	* @param pMod Pointer to the module structure.
318	*/
319	DECLCALLBACKMEMBER(int, pfnClose,(PRTDBGMODINT pMod));
320
321
322
323	/**
324	* Converts an image relative virtual address address to a segmented address.
325	*
326	* @returns Segment index on success, NIL_RTDBGSEGIDX on failure.
327	* @param pMod Pointer to the module structure.
328	* @param uRva The image relative address to convert.
329	* @param poffSeg Where to return the segment offset. Optional.
330	*/
331	DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnRvaToSegOff,(PRTDBGMODINT pMod, RTUINTPTR uRva, PRTUINTPTR poffSeg));
332
333	/**
334	* Image size when mapped if segments are mapped adjacently.
335	*
336	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
337	* NE and such it's a bit odder and the answer may not make much sense for them.
338	*
339	* @returns Image mapped size.
340	* @param pMod Pointer to the module structure.
341	*/
342	DECLCALLBACKMEMBER(RTUINTPTR, pfnImageSize,(PRTDBGMODINT pMod));
343
344
345
346	/**
347	* Adds a segment to the module (optional).
348	*
349	* @returns IPRT status code.
350	* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
351	* @retval VERR_DBG_SEGMENT_INDEX_CONFLICT if the segment index exists already.
352	*
353	* @param pMod Pointer to the module structure.
354	* @param uRva The segment image relative address.
355	* @param cb The segment size.
356	* @param pszName The segment name.
357	* @param cchName The length of the segment name.
358	* @param fFlags Segment flags.
359	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
360	* The assigned segment index on successful return.
361	* Optional.
362	*/
363	DECLCALLBACKMEMBER(int, pfnSegmentAdd,(PRTDBGMODINT pMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName, size_t cchName,
364	uint32_t fFlags, PRTDBGSEGIDX piSeg));
365
366	/**
367	* Gets the segment count.
368	*
369	* @returns Number of segments.
370	* @retval NIL_RTDBGSEGIDX if unknown.
371	*
372	* @param pMod Pointer to the module structure.
373	*/
374	DECLCALLBACKMEMBER(RTDBGSEGIDX, pfnSegmentCount,(PRTDBGMODINT pMod));
375
376	/**
377	* Gets information about a segment.
378	*
379	* @returns IPRT status code.
380	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
381	*
382	* @param pMod Pointer to the module structure.
383	* @param iSeg The segment.
384	* @param pSegInfo Where to store the segment information.
385	*/
386	DECLCALLBACKMEMBER(int, pfnSegmentByIndex,(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo));
387
388
389
390	/**
391	* Adds a symbol to the module (optional).
392	*
393	* @returns IPRT code.
394	* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
395	*
396	* @param pMod Pointer to the module structure.
397	* @param pszSymbol The symbol name.
398	* @param cchSymbol The length for the symbol name.
399	* @param iSeg The segment number (0-based). RTDBGMOD_SEG_RVA can be used.
400	* @param off The offset into the segment.
401	* @param cb The area covered by the symbol. 0 is fine.
402	* @param fFlags Flags.
403	* @param piOrdinal Where to return the symbol ordinal on success. If the
404	* interpreter doesn't do ordinals, this will be set to
405	* UINT32_MAX. Optional
406	*/
407	DECLCALLBACKMEMBER(int, pfnSymbolAdd,(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol,
408	uint32_t iSeg, RTUINTPTR off, RTUINTPTR cb, uint32_t fFlags,
409	uint32_t *piOrdinal));
410
411	/**
412	* Gets the number of symbols in the module.
413	*
414	* This is used for figuring out the max value to pass to pfnSymbolByIndex among
415	* other things.
416	*
417	* @returns The number of symbols, UINT32_MAX if not known/supported.
418	*
419	* @param pMod Pointer to the module structure.
420	*/
421	DECLCALLBACKMEMBER(uint32_t, pfnSymbolCount,(PRTDBGMODINT pMod));
422
423	/**
424	* Queries symbol information by ordinal number.
425	*
426	* @returns IPRT status code.
427	* @retval VINF_SUCCESS on success, no informational status code.
428	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
429	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
430	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at that index.
431	*
432	* @param pMod Pointer to the module structure.
433	* @param iOrdinal The symbol ordinal number.
434	* @param pSymInfo Where to store the symbol information.
435	*/
436	DECLCALLBACKMEMBER(int, pfnSymbolByOrdinal,(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo));
437
438	/**
439	* Queries symbol information by symbol name.
440	*
441	* @returns IPRT status code.
442	* @retval VINF_SUCCESS on success, no informational status code.
443	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
444	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
445	*
446	* @param pMod Pointer to the module structure.
447	* @param pszSymbol The symbol name.
448	* @param cchSymbol The length of the symbol name.
449	* @param pSymInfo Where to store the symbol information.
450	*/
451	DECLCALLBACKMEMBER(int, pfnSymbolByName,(PRTDBGMODINT pMod, const char *pszSymbol, size_t cchSymbol, PRTDBGSYMBOL pSymInfo));
452
453	/**
454	* Queries symbol information by address.
455	*
456	* The returned symbol is what the debug info interpreter considers the symbol
457	* most applicable to the specified address. This usually means a symbol with an
458	* address equal or lower than the requested.
459	*
460	* @returns IPRT status code.
461	* @retval VINF_SUCCESS on success, no informational status code.
462	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
463	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
464	*
465	* @param pMod Pointer to the module structure.
466	* @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
467	* @param off The offset into the segment.
468	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
469	* @param poffDisp Where to store the distance between the specified address
470	* and the returned symbol. Optional.
471	* @param pSymInfo Where to store the symbol information.
472	*/
473	DECLCALLBACKMEMBER(int, pfnSymbolByAddr,(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off, uint32_t fFlags,
474	PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo));
475
476
477
478	/**
479	* Adds a line number to the module (optional).
480	*
481	* @returns IPRT status code.
482	* @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
483	*
484	* @param pMod Pointer to the module structure.
485	* @param pszFile The filename.
486	* @param cchFile The length of the filename.
487	* @param uLineNo The line number.
488	* @param iSeg The segment number (0-based).
489	* @param off The offset into the segment.
490	* @param piOrdinal Where to return the line number ordinal on success. If
491	* the interpreter doesn't do ordinals, this will be set to
492	* UINT32_MAX. Optional
493	*/
494	DECLCALLBACKMEMBER(int, pfnLineAdd,(PRTDBGMODINT pMod, const char *pszFile, size_t cchFile, uint32_t uLineNo,
495	uint32_t iSeg, RTUINTPTR off, uint32_t *piOrdinal));
496
497	/**
498	* Gets the number of line numbers in the module.
499	*
500	* @returns The number or UINT32_MAX if not known/supported.
501	*
502	* @param pMod Pointer to the module structure.
503	*/
504	DECLCALLBACKMEMBER(uint32_t, pfnLineCount,(PRTDBGMODINT pMod));
505
506	/**
507	* Queries line number information by ordinal number.
508	*
509	* @returns IPRT status code.
510	* @retval VINF_SUCCESS on success, no informational status code.
511	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
512	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
513	* ordinal.
514	*
515	* @param pMod Pointer to the module structure.
516	* @param iOrdinal The line number ordinal number.
517	* @param pLineInfo Where to store the information about the line number.
518	*/
519	DECLCALLBACKMEMBER(int, pfnLineByOrdinal,(PRTDBGMODINT pMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo));
520
521	/**
522	* Queries line number information by address.
523	*
524	* @returns IPRT status code.
525	* @retval VINF_SUCCESS on success, no informational status code.
526	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
527	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
528	*
529	* @param pMod Pointer to the module structure.
530	* @param iSeg The segment number (0-based) or RTDBGSEGIDX_ABS.
531	* @param off The offset into the segment.
532	* @param poffDisp Where to store the distance between the specified address
533	* and the returned line number. Optional.
534	* @param pLineInfo Where to store the information about the closest line
535	* number.
536	*/
537	DECLCALLBACKMEMBER(int, pfnLineByAddr,(PRTDBGMODINT pMod, uint32_t iSeg, RTUINTPTR off,
538	PRTINTPTR poffDisp, PRTDBGLINE pLineInfo));
539
540	/**
541	* Try use unwind information to unwind one frame.
542	*
543	* @returns IPRT status code. Last informational status from stack reader callback.
544	* @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
545	* @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
546	* for the location given by iSeg:off.
547	*
548	* @param pMod Pointer to the module structure.
549	* @param iSeg The segment number of the program counter.
550	* @param off The offset into @a iSeg. Together with @a iSeg
551	* this corresponds to the RTDBGUNWINDSTATE::uPc
552	* value pointed to by @a pState.
553	* @param pState The unwind state to work.
554	*
555	* @sa RTDbgModUnwindFrame
556	*/
557	DECLCALLBACKMEMBER(int, pfnUnwindFrame,(PRTDBGMODINT pMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTDBGUNWINDSTATE pState));
558
559	/** For catching initialization errors (RTDBGMODVTDBG_MAGIC). */
560	uint32_t u32EndMagic;
561	} RTDBGMODVTDBG;
562	/** Pointer to a const RTDBGMODVTDBG. */
563	typedef RTDBGMODVTDBG const *PCRTDBGMODVTDBG;
564
565
566	/**
567	* Deferred loading callback.
568	*
569	* @returns IPRT status code. On success the necessary method tables should be
570	* installed in @a pMod.
571	* @param pDbgMod Pointer to the debug module structure.
572	* @param pDeferred The deferred load data.
573	*/
574	typedef DECLCALLBACKTYPE(int, FNRTDBGMODDEFERRED,(PRTDBGMODINT pDbgMod, struct RTDBGMODDEFERRED *pDeferred));
575	/** Pointer to a deferred loading callback. */
576	typedef FNRTDBGMODDEFERRED *PFNRTDBGMODDEFERRED;
577
578
579	/**
580	* Structure pointed to by pvDbgPriv and/or pvImgPriv when
581	* g_rtDbgModVtDbgDeferred and/or g_rtDbgModVtImgDeferred are being used.
582	*/
583	typedef struct RTDBGMODDEFERRED
584	{
585	/** Magic value (RTDBGMODDEFERRED_MAGIC). */
586	uint32_t u32Magic;
587	/** Reference counter. */
588	uint32_t volatile cRefs;
589	/** RTDBGMOD_F_XXX */
590	uint32_t fFlags;
591	/** The image size.
592	* Deferred loading is almost pointless without knowing the module size, as
593	* it cannot be mapped (correctly) without it. */
594	RTUINTPTR cbImage;
595	/** The configuration instance (referenced), can be NIL. */
596	RTDBGCFG hDbgCfg;
597	/** Performs deferred loading of the module. */
598	PFNRTDBGMODDEFERRED pfnDeferred;
599	/** Callback specific data. */
600	union
601	{
602	struct
603	{
604	/** The time/date stamp of the executable image and codeview file. */
605	uint32_t uTimestamp;
606	} PeImage,
607	OldCodeView;
608
609	struct
610	{
611	/** The PDB uuid. */
612	RTUUID Uuid;
613	/** The PDB age. */
614	uint32_t uAge;
615	} NewCodeview;
616
617	struct
618	{
619	/** The CRC-32 value found in the .gnu_debuglink section. */
620	uint32_t uCrc32;
621	} GnuDebugLink;
622
623	struct
624	{
625	/** The image UUID. */
626	RTUUID Uuid;
627	/** Image architecture. */
628	RTLDRARCH enmArch;
629	/** Number of segment mappings. */
630	uint32_t cSegs;
631	/** Segment mappings. */
632	RTDBGSEGMENT aSegs[1];
633	} MachO;
634	} u;
635	} RTDBGMODDEFERRED;
636	/** Pointer to the deferred loading data. */
637	typedef RTDBGMODDEFERRED *PRTDBGMODDEFERRED;
638
639
640	/**
641	* Debug module structure.
642	*/
643	typedef struct RTDBGMODINT
644	{
645	/** Magic value (RTDBGMOD_MAGIC). */
646	uint32_t u32Magic;
647	/** The number of reference there are to this module.
648	* This is used to perform automatic cleanup and sharing. */
649	uint32_t volatile cRefs;
650	/** The module tag. */
651	uint64_t uTag;
652
653	/** When set, the loading of the image and debug info (including locating any
654	* external files), will not have taken place yet. */
655	uint32_t fDeferred : 1;
656	/** Set if deferred loading failed. */
657	uint32_t fDeferredFailed : 1;
658	/** Set if the debug info is based on image exports and segments. */
659	uint32_t fExports : 1;
660	/** Alignment padding. */
661	uint32_t fPadding1 : 29;
662	#if ARCH_BITS == 64
663	uint32_t u32Padding2;
664	#endif
665
666	/** The module name (short). */
667	char const *pszName;
668	/** The image file specified by the user. Can be NULL. */
669	char const *pszImgFileSpecified;
670	/** The module filename. Can be NULL. */
671	char const *pszImgFile;
672	/** The debug info file (if external). Can be NULL. */
673	char const *pszDbgFile;
674
675	/** The method table for the executable image interpreter. */
676	PCRTDBGMODVTIMG pImgVt;
677	/** Pointer to the private data of the executable image interpreter. */
678	void *pvImgPriv;
679
680	/** The method table for the debug info interpreter. */
681	PCRTDBGMODVTDBG pDbgVt;
682	/** Pointer to the private data of the debug info interpreter. */
683	void *pvDbgPriv;
684
685	/** Critical section serializing access to the module. */
686	RTCRITSECT CritSect;
687	} RTDBGMODINT;
688	/** Pointer to an debug module structure. */
689	typedef RTDBGMODINT *PRTDBGMODINT;
690
691
692	extern DECLHIDDEN(RTSTRCACHE) g_hDbgModStrCache;
693	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgCodeView;
694	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDwarf;
695	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
696	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgMapSym;
697	#ifdef RT_OS_WINDOWS
698	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDbgHelp;
699	#endif
700	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgDeferred;
701	extern DECLHIDDEN(RTDBGMODVTDBG const) g_rtDbgModVtDbgContainer;
702
703	extern DECLHIDDEN(RTDBGMODVTIMG const) g_rtDbgModVtImgLdr;
704	extern DECLHIDDEN(RTDBGMODVTIMG const) g_rtDbgModVtImgDeferred;
705
706	DECLHIDDEN(int) rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
707	DECLHIDDEN(int) rtDbgModContainer_SymbolRemoveAll(PRTDBGMODINT pMod);
708	DECLHIDDEN(int) rtDbgModContainer_LineRemoveAll(PRTDBGMODINT pMod);
709	DECLHIDDEN(int) rtDbgModContainer_RemoveAll(PRTDBGMODINT pMod);
710
711	DECLHIDDEN(int) rtDbgModCreateForExports(PRTDBGMODINT pDbgMod);
712	DECLHIDDEN(int) rtDbgModDeferredCreate(PRTDBGMODINT pDbgMod, PFNRTDBGMODDEFERRED pfnDeferred, RTUINTPTR cbImage,
713	RTDBGCFG hDbgCfg, size_t cbDeferred, uint32_t fFlags, PRTDBGMODDEFERRED *ppDeferred);
714
715	DECLHIDDEN(int) rtDbgModLdrOpenFromHandle(PRTDBGMODINT pDbgMod, RTLDRMOD hLdrMod);
716
717	DECLHIDDEN(int) rtDwarfUnwind_EhData(void const *pvSection, size_t cbSection, RTUINTPTR uRvaSection,
718	RTDBGSEGIDX idxSeg, RTUINTPTR offSeg, RTUINTPTR uRva,
719	PRTDBGUNWINDSTATE pState, RTLDRARCH enmArch);
720
721	/** @} */
722
723	RT_C_DECLS_END
724
725	#endif /* !IPRT_INCLUDED_INTERNAL_dbgmod_h */
726

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

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

Download in other formats: