VirtualBox

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

Last change on this file was 100931, checked in by vboxsync, 9 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
48RT_C_DECLS_BEGIN
49
50/** @addtogroup grp_rt_dbgmod
51 * @internal
52 * @{
53 */
54
55
56/** Pointer to the internal module structure. */
57typedef struct RTDBGMODINT *PRTDBGMODINT;
58
59/**
60 * Virtual method table for executable image interpreters.
61 */
62typedef 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. */
282typedef RTDBGMODVTIMG const *PCRTDBGMODVTIMG;
283
284
285/**
286 * Virtual method table for debug info interpreters.
287 */
288typedef 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. */
579typedef 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 */
590typedef DECLCALLBACKTYPE(int, FNRTDBGMODDEFERRED,(PRTDBGMODINT pDbgMod, struct RTDBGMODDEFERRED *pDeferred));
591/** Pointer to a deferred loading callback. */
592typedef 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 */
599typedef 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. */
653typedef RTDBGMODDEFERRED *PRTDBGMODDEFERRED;
654
655
656/**
657 * Debug module structure.
658 */
659typedef 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. */
705typedef RTDBGMODINT *PRTDBGMODINT;
706
707
708extern DECL_HIDDEN_DATA(RTSTRCACHE) g_hDbgModStrCache;
709extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgCodeView;
710extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgPdb;
711extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDwarf;
712extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgNm;
713extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgMapSym;
714#ifdef IPRT_WITH_GHIDRA_DBG_MOD
715extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgGhidra;
716#endif
717#ifdef RT_OS_WINDOWS
718extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDbgHelp;
719#endif
720extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgDeferred;
721extern DECL_HIDDEN_DATA(RTDBGMODVTDBG const) g_rtDbgModVtDbgContainer;
722
723extern DECL_HIDDEN_DATA(RTDBGMODVTIMG const) g_rtDbgModVtImgLdr;
724extern DECL_HIDDEN_DATA(RTDBGMODVTIMG const) g_rtDbgModVtImgDeferred;
725
726DECLHIDDEN(int) rtDbgModContainerCreate(PRTDBGMODINT pMod, RTUINTPTR cbSeg);
727DECLHIDDEN(int) rtDbgModContainer_SymbolRemoveAll(PRTDBGMODINT pMod);
728DECLHIDDEN(int) rtDbgModContainer_LineRemoveAll(PRTDBGMODINT pMod);
729DECLHIDDEN(int) rtDbgModContainer_RemoveAll(PRTDBGMODINT pMod);
730
731DECLHIDDEN(int) rtDbgModCreateForExports(PRTDBGMODINT pDbgMod);
732DECLHIDDEN(int) rtDbgModDeferredCreate(PRTDBGMODINT pDbgMod, PFNRTDBGMODDEFERRED pfnDeferred, RTUINTPTR cbImage,
733 RTDBGCFG hDbgCfg, size_t cbDeferred, uint32_t fFlags, PRTDBGMODDEFERRED *ppDeferred);
734
735DECLHIDDEN(int) rtDbgModLdrOpenFromHandle(PRTDBGMODINT pDbgMod, RTLDRMOD hLdrMod);
736
737DECLHIDDEN(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
743RT_C_DECLS_END
744
745#endif /* !IPRT_INCLUDED_INTERNAL_dbgmod_h */
746
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use