dbgmod.h@ 104465

Last change on this file since 104465 was 100931, checked in by vboxsync, 16 months ago
IPRT/dbg: Early PDB support.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 29.6 KB

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

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

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

Download in other formats: