dbgmod.h@ 91999

Last change on this file since 91999 was 89881, checked in by vboxsync, 3 years ago
Runtime/common/dbg: Implement basic debug info reader for XML files created by Ghidra's createPdbXmlFiles.bat script in order to get more accurate symbols when debugging Windows guests on hosts other than Windows due to the lack of a dbghelp.dll equivalent for accessing the debugging information inside of PDB files. This requires creating the XML files on a Windows machine with a matching set of PDB files. XML files can be loaded with the loadmap debugger command for now (automatic loading not implemented right now)
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 28.8 KB

Line
1	/* $Id: dbgmod.h 89881 2021-06-24 10:58:04Z 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 DECL_HIDDEN_DATA(RTSTRCACHE) g_hDbgModStrCache;
693	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgCodeView;
694	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDwarf;
695	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
696	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgMapSym;
697	#ifdef IPRT_WITH_GHIDRA_DBG_MOD
698	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgGhidra;
699	#endif
700	#ifdef RT_OS_WINDOWS
701	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDbgHelp;
702	#endif
703	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDeferred;
704	extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgContainer;
705
706	extern DECL_HIDDEN_DATA(RTDBGMODVTIMG const) g_rtDbgModVtImgLdr;
707	extern DECL_HIDDEN_DATA(RTDBGMODVTIMG const) g_rtDbgModVtImgDeferred;
708
709	DECLHIDDEN(int) rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
710	DECLHIDDEN(int) rtDbgModContainer_SymbolRemoveAll(PRTDBGMODINT pMod);
711	DECLHIDDEN(int) rtDbgModContainer_LineRemoveAll(PRTDBGMODINT pMod);
712	DECLHIDDEN(int) rtDbgModContainer_RemoveAll(PRTDBGMODINT pMod);
713
714	DECLHIDDEN(int) rtDbgModCreateForExports(PRTDBGMODINT pDbgMod);
715	DECLHIDDEN(int) rtDbgModDeferredCreate(PRTDBGMODINT pDbgMod, PFNRTDBGMODDEFERRED pfnDeferred, RTUINTPTR cbImage,
716	RTDBGCFG hDbgCfg, size_t cbDeferred, uint32_t fFlags, PRTDBGMODDEFERRED *ppDeferred);
717
718	DECLHIDDEN(int) rtDbgModLdrOpenFromHandle(PRTDBGMODINT pDbgMod, RTLDRMOD hLdrMod);
719
720	DECLHIDDEN(int) rtDwarfUnwind_EhData(void const *pvSection, size_t cbSection, RTUINTPTR uRvaSection,
721	RTDBGSEGIDX idxSeg, RTUINTPTR offSeg, RTUINTPTR uRva,
722	PRTDBGUNWINDSTATE pState, RTLDRARCH enmArch);
723
724	/** @} */
725
726	RT_C_DECLS_END
727
728	#endif /* !IPRT_INCLUDED_INTERNAL_dbgmod_h */
729

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

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

Download in other formats: