VirtualBox

source: vbox/trunk/include/iprt/dbg.h@ 76327

Last change on this file since 76327 was 75239, checked in by vboxsync, 6 years ago

IPRT/dbg: Added RTDbgCfgOpenEx.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 77.8 KB
Line 
1/* $Id: dbg.h 75239 2018-11-03 02:54:26Z vboxsync $ */
2/** @file
3 * IPRT - Debugging Routines.
4 */
5
6/*
7 * Copyright (C) 2008-2017 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_dbg_h
28#define ___iprt_dbg_h
29
30#include <iprt/types.h>
31#include <iprt/stdarg.h>
32#include <iprt/ldr.h>
33
34RT_C_DECLS_BEGIN
35
36
37/** @defgroup grp_rt_dbg RTDbg - Debugging Routines
38 * @ingroup grp_rt
39 * @{
40 */
41
42
43/** Debug segment index. */
44typedef uint32_t RTDBGSEGIDX;
45/** Pointer to a debug segment index. */
46typedef RTDBGSEGIDX *PRTDBGSEGIDX;
47/** Pointer to a const debug segment index. */
48typedef RTDBGSEGIDX const *PCRTDBGSEGIDX;
49/** NIL debug segment index. */
50#define NIL_RTDBGSEGIDX UINT32_C(0xffffffff)
51/** The last normal segment index. */
52#define RTDBGSEGIDX_LAST UINT32_C(0xffffffef)
53/** Special segment index that indicates that the offset is a relative
54 * virtual address (RVA). I.e. an offset from the start of the module. */
55#define RTDBGSEGIDX_RVA UINT32_C(0xfffffff0)
56/** Special segment index that indicates that the offset is a absolute. */
57#define RTDBGSEGIDX_ABS UINT32_C(0xfffffff1)
58/** The last valid special segment index. */
59#define RTDBGSEGIDX_SPECIAL_LAST RTDBGSEGIDX_ABS
60/** The last valid special segment index. */
61#define RTDBGSEGIDX_SPECIAL_FIRST (RTDBGSEGIDX_LAST + 1U)
62
63
64
65/** @name RTDBGSYMADDR_FLAGS_XXX
66 * Flags used when looking up a symbol by address.
67 * @{ */
68/** Less or equal address. (default) */
69#define RTDBGSYMADDR_FLAGS_LESS_OR_EQUAL UINT32_C(0)
70/** Greater or equal address. */
71#define RTDBGSYMADDR_FLAGS_GREATER_OR_EQUAL UINT32_C(1)
72/** Don't consider absolute symbols in deferred modules. */
73#define RTDBGSYMADDR_FLAGS_SKIP_ABS_IN_DEFERRED UINT32_C(2)
74/** Don't search for absolute symbols if it's expensive. */
75#define RTDBGSYMADDR_FLAGS_SKIP_ABS UINT32_C(4)
76/** Mask of valid flags. */
77#define RTDBGSYMADDR_FLAGS_VALID_MASK UINT32_C(7)
78/** @} */
79
80/** @name RTDBGSYMBOLADD_F_XXX - Flags for RTDbgModSymbolAdd and RTDbgAsSymbolAdd.
81 * @{ */
82/** Replace existing symbol with same address. */
83#define RTDBGSYMBOLADD_F_REPLACE_SAME_ADDR UINT32_C(0x00000001)
84/** Replace any existing symbols overlapping the symbol range. */
85#define RTDBGSYMBOLADD_F_REPLACE_ANY UINT32_C(0x00000002)
86/** Adjust sizes on address conflict. This applies to the symbol being added
87 * as well as existing symbols. */
88#define RTDBGSYMBOLADD_F_ADJUST_SIZES_ON_CONFLICT UINT32_C(0x00000004)
89/** Mask of valid flags. */
90#define RTDBGSYMBOLADD_F_VALID_MASK UINT32_C(0x00000007)
91/** @} */
92
93/** Max length (including '\\0') of a segment name. */
94#define RTDBG_SEGMENT_NAME_LENGTH (128 - 8 - 8 - 8 - 4 - 4)
95
96/**
97 * Debug module segment.
98 */
99typedef struct RTDBGSEGMENT
100{
101 /** The load address.
102 * RTUINTPTR_MAX if not applicable. */
103 RTUINTPTR Address;
104 /** The image relative virtual address of the segment.
105 * RTUINTPTR_MAX if not applicable. */
106 RTUINTPTR uRva;
107 /** The segment size. */
108 RTUINTPTR cb;
109 /** The segment flags. (reserved) */
110 uint32_t fFlags;
111 /** The segment index. */
112 RTDBGSEGIDX iSeg;
113 /** Symbol name. */
114 char szName[RTDBG_SEGMENT_NAME_LENGTH];
115} RTDBGSEGMENT;
116/** Pointer to a debug module segment. */
117typedef RTDBGSEGMENT *PRTDBGSEGMENT;
118/** Pointer to a const debug module segment. */
119typedef RTDBGSEGMENT const *PCRTDBGSEGMENT;
120
121
122/**
123 * Return type.
124 */
125typedef enum RTDBGRETURNTYPE
126{
127 /** The usual invalid 0 value. */
128 RTDBGRETURNTYPE_INVALID = 0,
129 /** Near 16-bit return. */
130 RTDBGRETURNTYPE_NEAR16,
131 /** Near 32-bit return. */
132 RTDBGRETURNTYPE_NEAR32,
133 /** Near 64-bit return. */
134 RTDBGRETURNTYPE_NEAR64,
135 /** Far 16:16 return. */
136 RTDBGRETURNTYPE_FAR16,
137 /** Far 16:32 return. */
138 RTDBGRETURNTYPE_FAR32,
139 /** Far 16:64 return. */
140 RTDBGRETURNTYPE_FAR64,
141 /** 16-bit iret return (e.g. real or 286 protect mode). */
142 RTDBGRETURNTYPE_IRET16,
143 /** 32-bit iret return. */
144 RTDBGRETURNTYPE_IRET32,
145 /** 32-bit iret return. */
146 RTDBGRETURNTYPE_IRET32_PRIV,
147 /** 32-bit iret return to V86 mode. */
148 RTDBGRETURNTYPE_IRET32_V86,
149 /** @todo 64-bit iret return. */
150 RTDBGRETURNTYPE_IRET64,
151 /** The end of the valid return types. */
152 RTDBGRETURNTYPE_END,
153 /** The usual 32-bit blowup. */
154 RTDBGRETURNTYPE_32BIT_HACK = 0x7fffffff
155} RTDBGRETURNTYPE;
156
157/**
158 * Figures the size of the return state on the stack.
159 *
160 * @returns number of bytes. 0 if invalid parameter.
161 * @param enmRetType The type of return.
162 */
163DECLINLINE(unsigned) RTDbgReturnTypeSize(RTDBGRETURNTYPE enmRetType)
164{
165 switch (enmRetType)
166 {
167 case RTDBGRETURNTYPE_NEAR16: return 2;
168 case RTDBGRETURNTYPE_NEAR32: return 4;
169 case RTDBGRETURNTYPE_NEAR64: return 8;
170 case RTDBGRETURNTYPE_FAR16: return 4;
171 case RTDBGRETURNTYPE_FAR32: return 4;
172 case RTDBGRETURNTYPE_FAR64: return 8;
173 case RTDBGRETURNTYPE_IRET16: return 6;
174 case RTDBGRETURNTYPE_IRET32: return 4*3;
175 case RTDBGRETURNTYPE_IRET32_PRIV: return 4*5;
176 case RTDBGRETURNTYPE_IRET32_V86: return 4*9;
177 case RTDBGRETURNTYPE_IRET64: return 5*8;
178
179 case RTDBGRETURNTYPE_INVALID:
180 case RTDBGRETURNTYPE_END:
181 case RTDBGRETURNTYPE_32BIT_HACK:
182 break;
183 }
184 return 0;
185}
186
187/**
188 * Check if near return.
189 *
190 * @returns true if near, false if far or iret.
191 * @param enmRetType The type of return.
192 */
193DECLINLINE(bool) RTDbgReturnTypeIsNear(RTDBGRETURNTYPE enmRetType)
194{
195 return enmRetType == RTDBGRETURNTYPE_NEAR32
196 || enmRetType == RTDBGRETURNTYPE_NEAR64
197 || enmRetType == RTDBGRETURNTYPE_NEAR16;
198}
199
200
201
202/** Magic value for RTDBGUNWINDSTATE::u32Magic (James Moody). */
203#define RTDBGUNWINDSTATE_MAGIC UINT32_C(0x19250326)
204/** Magic value for RTDBGUNWINDSTATE::u32Magic after use. */
205#define RTDBGUNWINDSTATE_MAGIC_DEAD UINT32_C(0x20101209)
206
207/**
208 * Unwind machine state.
209 */
210typedef struct RTDBGUNWINDSTATE
211{
212 /** Structure magic (RTDBGUNWINDSTATE_MAGIC) */
213 uint32_t u32Magic;
214 /** The state architecture. */
215 RTLDRARCH enmArch;
216
217 /** The program counter register.
218 * amd64/x86: RIP/EIP/IP
219 * sparc: PC
220 * arm32: PC / R15
221 */
222 uint64_t uPc;
223
224 /** Return type. */
225 RTDBGRETURNTYPE enmRetType;
226
227 /** Register state (see enmArch). */
228 union
229 {
230 /** RTLDRARCH_AMD64, RTLDRARCH_X86_32 and RTLDRARCH_X86_16. */
231 struct
232 {
233 /** General purpose registers indexed by X86_GREG_XXX. */
234 uint64_t auRegs[16];
235 /** The frame address. */
236 RTFAR64 FrameAddr;
237 /** Set if we're in real or virtual 8086 mode. */
238 bool fRealOrV86;
239 /** The flags register. */
240 uint64_t uRFlags;
241 /** Trap error code. */
242 uint64_t uErrCd;
243 /** Segment registers (indexed by X86_SREG_XXX). */
244 uint16_t auSegs[6];
245
246 /** Bitmap tracking register we've loaded and which content can possibly be trusted. */
247 union
248 {
249 /** For effective clearing of the bits. */
250 uint32_t fAll;
251 /** Detailed view. */
252 struct
253 {
254 /** Bitmap indicating whether a GPR was loaded (parallel to auRegs). */
255 uint16_t fRegs;
256 /** Bitmap indicating whether a segment register was loaded (parallel to auSegs). */
257 uint8_t fSegs;
258 /** Set if uPc was loaded. */
259 RT_GCC_EXTENSION uint8_t fPc : 1;
260 /** Set if FrameAddr was loaded. */
261 RT_GCC_EXTENSION uint8_t fFrameAddr : 1;
262 /** Set if uRFlags was loaded. */
263 RT_GCC_EXTENSION uint8_t fRFlags : 1;
264 /** Set if uErrCd was loaded. */
265 RT_GCC_EXTENSION uint8_t fErrCd : 1;
266 } s;
267 } Loaded;
268 } x86;
269
270 /** @todo add ARM and others as needed. */
271 } u;
272
273 /**
274 * Stack read callback.
275 *
276 * @returns IPRT status code.
277 * @param pThis Pointer to this structure.
278 * @param uSp The stack pointer address.
279 * @param cbToRead The number of bytes to read.
280 * @param pvDst Where to put the bytes we read.
281 */
282 DECLCALLBACKMEMBER(int, pfnReadStack)(struct RTDBGUNWINDSTATE *pThis, RTUINTPTR uSp, size_t cbToRead, void *pvDst);
283 /** User argument (useful for pfnReadStack). */
284 void *pvUser;
285
286} RTDBGUNWINDSTATE;
287
288/**
289 * Try read a 16-bit value off the stack.
290 *
291 * @returns pfnReadStack result.
292 * @param pThis The unwind state.
293 * @param uSrcAddr The stack address.
294 * @param puDst The read destination.
295 */
296DECLINLINE(int) RTDbgUnwindLoadStackU16(PRTDBGUNWINDSTATE pThis, RTUINTPTR uSrcAddr, uint16_t *puDst)
297{
298 return pThis->pfnReadStack(pThis, uSrcAddr, sizeof(*puDst), puDst);
299}
300
301/**
302 * Try read a 32-bit value off the stack.
303 *
304 * @returns pfnReadStack result.
305 * @param pThis The unwind state.
306 * @param uSrcAddr The stack address.
307 * @param puDst The read destination.
308 */
309DECLINLINE(int) RTDbgUnwindLoadStackU32(PRTDBGUNWINDSTATE pThis, RTUINTPTR uSrcAddr, uint32_t *puDst)
310{
311 return pThis->pfnReadStack(pThis, uSrcAddr, sizeof(*puDst), puDst);
312}
313
314/**
315 * Try read a 64-bit value off the stack.
316 *
317 * @returns pfnReadStack result.
318 * @param pThis The unwind state.
319 * @param uSrcAddr The stack address.
320 * @param puDst The read destination.
321 */
322DECLINLINE(int) RTDbgUnwindLoadStackU64(PRTDBGUNWINDSTATE pThis, RTUINTPTR uSrcAddr, uint64_t *puDst)
323{
324 return pThis->pfnReadStack(pThis, uSrcAddr, sizeof(*puDst), puDst);
325}
326
327
328
329/** Max length (including '\\0') of a symbol name. */
330#define RTDBG_SYMBOL_NAME_LENGTH (512 - 8 - 8 - 8 - 4 - 4 - 8)
331
332/**
333 * Debug symbol.
334 */
335typedef struct RTDBGSYMBOL
336{
337 /** Symbol value (address).
338 * This depends a bit who you ask. It will be the same as offSeg when you
339 * as RTDbgMod, but the mapping address if you ask RTDbgAs. */
340 RTUINTPTR Value;
341 /** Symbol size. */
342 RTUINTPTR cb;
343 /** Offset into the segment specified by iSeg. */
344 RTUINTPTR offSeg;
345 /** Segment number. */
346 RTDBGSEGIDX iSeg;
347 /** Symbol Flags. (reserved). */
348 uint32_t fFlags;
349 /** Symbol ordinal.
350 * This is set to UINT32_MAX if the ordinals aren't supported. */
351 uint32_t iOrdinal;
352 /** Symbol name. */
353 char szName[RTDBG_SYMBOL_NAME_LENGTH];
354} RTDBGSYMBOL;
355/** Pointer to debug symbol. */
356typedef RTDBGSYMBOL *PRTDBGSYMBOL;
357/** Pointer to const debug symbol. */
358typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
359
360
361/**
362 * Allocate a new symbol structure.
363 *
364 * @returns Pointer to a new structure on success, NULL on failure.
365 */
366RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void);
367
368/**
369 * Duplicates a symbol structure.
370 *
371 * @returns Pointer to duplicate on success, NULL on failure.
372 *
373 * @param pSymInfo The symbol info to duplicate.
374 */
375RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymInfo);
376
377/**
378 * Free a symbol structure previously allocated by a RTDbg method.
379 *
380 * @param pSymInfo The symbol info to free. NULL is ignored.
381 */
382RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymInfo);
383
384
385/** Max length (including '\\0') of a debug info file name. */
386#define RTDBG_FILE_NAME_LENGTH (260)
387
388
389/**
390 * Debug line number information.
391 */
392typedef struct RTDBGLINE
393{
394 /** Address.
395 * This depends a bit who you ask. It will be the same as offSeg when you
396 * as RTDbgMod, but the mapping address if you ask RTDbgAs. */
397 RTUINTPTR Address;
398 /** Offset into the segment specified by iSeg. */
399 RTUINTPTR offSeg;
400 /** Segment number. */
401 RTDBGSEGIDX iSeg;
402 /** Line number. */
403 uint32_t uLineNo;
404 /** Symbol ordinal.
405 * This is set to UINT32_MAX if the ordinals aren't supported. */
406 uint32_t iOrdinal;
407 /** Filename. */
408 char szFilename[RTDBG_FILE_NAME_LENGTH];
409} RTDBGLINE;
410/** Pointer to debug line number. */
411typedef RTDBGLINE *PRTDBGLINE;
412/** Pointer to const debug line number. */
413typedef const RTDBGLINE *PCRTDBGLINE;
414
415/**
416 * Allocate a new line number structure.
417 *
418 * @returns Pointer to a new structure on success, NULL on failure.
419 */
420RTDECL(PRTDBGLINE) RTDbgLineAlloc(void);
421
422/**
423 * Duplicates a line number structure.
424 *
425 * @returns Pointer to duplicate on success, NULL on failure.
426 *
427 * @param pLine The line number to duplicate.
428 */
429RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);
430
431/**
432 * Free a line number structure previously allocated by a RTDbg method.
433 *
434 * @param pLine The line number to free. NULL is ignored.
435 */
436RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine);
437
438
439/**
440 * Dump the stack of the current thread into @a pszStack.
441 *
442 * This could be a little slow as it reads image and debug info again for each call.
443 *
444 * @returns Length of string returned in @a pszStack.
445 * @param pszStack The output buffer.
446 * @param cbStack The size of the output buffer.
447 * @param fFlags Future flags, MBZ.
448 *
449 * @remarks Not present on all systems and contexts.
450 */
451RTDECL(size_t) RTDbgStackDumpSelf(char *pszStack, size_t cbStack, uint32_t fFlags);
452
453
454# ifdef IN_RING3
455
456/** @defgroup grp_rt_dbgcfg RTDbgCfg - Debugging Configuration
457 *
458 * The settings used when loading and processing debug info is kept in a
459 * RTDBGCFG instance since it's generally shared for a whole debugging session
460 * and anyhow would be a major pain to pass as individual parameters to each
461 * call. The debugging config API not only keeps the settings information but
462 * also provide APIs for making use of it, and in some cases, like for instance
463 * symbol severs, retriving and maintaining it.
464 *
465 * @todo Work in progress - APIs are still missing, adding when needed.
466 *
467 * @{
468 */
469
470/** Debugging configuration handle. */
471typedef struct RTDBGCFGINT *RTDBGCFG;
472/** Pointer to a debugging configuration handle. */
473typedef RTDBGCFG *PRTDBGCFG;
474/** NIL debug configuration handle. */
475#define NIL_RTDBGCFG ((RTDBGCFG)0)
476
477/** @name RTDBGCFG_FLAGS_XXX - Debugging configuration flags.
478 * @{ */
479/** Use deferred loading. */
480#define RTDBGCFG_FLAGS_DEFERRED RT_BIT_64(0)
481/** Don't use the symbol server (http). */
482#define RTDBGCFG_FLAGS_NO_SYM_SRV RT_BIT_64(1)
483/** Don't use system search paths.
484 * On windows this means not using _NT_ALT_SYMBOL_PATH, _NT_SYMBOL_PATH,
485 * _NT_SOURCE_PATH, and _NT_EXECUTABLE_PATH.
486 * On other systems the effect has yet to be determined. */
487#define RTDBGCFG_FLAGS_NO_SYSTEM_PATHS RT_BIT_64(2)
488/** Don't search the debug and image paths recursively. */
489#define RTDBGCFG_FLAGS_NO_RECURSIV_SEARCH RT_BIT_64(3)
490/** Don't search the source paths recursively. */
491#define RTDBGCFG_FLAGS_NO_RECURSIV_SRC_SEARCH RT_BIT_64(4)
492/** @} */
493
494/**
495 * Debugging configuration properties.
496 *
497 * The search paths are using the DOS convention of semicolon as separator
498 * character. The the special 'srv' + asterisk syntax known from the windows
499 * debugger search paths are also supported to some extent, as is 'cache' +
500 * asterisk.
501 */
502typedef enum RTDBGCFGPROP
503{
504 /** The customary invalid 0 value. */
505 RTDBGCFGPROP_INVALID = 0,
506 /** RTDBGCFG_FLAGS_XXX.
507 * Env: _FLAGS
508 * The environment variable can be specified as a unsigned value or one or more
509 * mnemonics separated by spaces. */
510 RTDBGCFGPROP_FLAGS,
511 /** List of paths to search for symbol files and images.
512 * Env: _PATH */
513 RTDBGCFGPROP_PATH,
514 /** List of symbol file suffixes (semicolon separated).
515 * Env: _SUFFIXES */
516 RTDBGCFGPROP_SUFFIXES,
517 /** List of paths to search for source files.
518 * Env: _SRC_PATH */
519 RTDBGCFGPROP_SRC_PATH,
520 /** End of valid values. */
521 RTDBGCFGPROP_END,
522 /** The customary 32-bit type hack. */
523 RTDBGCFGPROP_32BIT_HACK = 0x7fffffff
524} RTDBGCFGPROP;
525
526/**
527 * Configuration property change operation.
528 */
529typedef enum RTDBGCFGOP
530{
531 /** Customary invalid 0 value. */
532 RTDBGCFGOP_INVALID = 0,
533 /** Replace the current value with the given one. */
534 RTDBGCFGOP_SET,
535 /** Append the given value to the existing one. For integer values this is
536 * considered a bitwise OR operation. */
537 RTDBGCFGOP_APPEND,
538 /** Prepend the given value to the existing one. For integer values this is
539 * considered a bitwise OR operation. */
540 RTDBGCFGOP_PREPEND,
541 /** Removes the value from the existing one. For interger values the value is
542 * complemented and ANDed with the existing one, clearing all the specified
543 * flags/bits. */
544 RTDBGCFGOP_REMOVE,
545 /** End of valid values. */
546 RTDBGCFGOP_END,
547 /** Customary 32-bit type hack. */
548 RTDBGCFGOP_32BIT_HACK = 0x7fffffff
549} RTDBGCFGOP;
550
551
552
553/**
554 * Initializes a debugging configuration.
555 *
556 * @returns IPRT status code.
557 * @param phDbgCfg Where to return the configuration handle.
558 * @param pszEnvVarPrefix The environment variable prefix. If NULL, the
559 * environment is not consulted.
560 * @param fNativePaths Whether to pick up native paths from the
561 * environment.
562 *
563 * @sa RTDbgCfgChangeString, RTDbgCfgChangeUInt.
564 */
565RTDECL(int) RTDbgCfgCreate(PRTDBGCFG phDbgCfg, const char *pszEnvVarPrefix, bool fNativePaths);
566
567/**
568 * Retains a new reference to a debugging config.
569 *
570 * @returns New reference count.
571 * UINT32_MAX is returned if the handle is invalid (asserted).
572 * @param hDbgCfg The config handle.
573 */
574RTDECL(uint32_t) RTDbgCfgRetain(RTDBGCFG hDbgCfg);
575
576/**
577 * Releases a references to a debugging config.
578 *
579 * @returns New reference count, if 0 the config was freed. UINT32_MAX is
580 * returned if the handle is invalid (asserted).
581 * @param hDbgCfg The config handle.
582 */
583RTDECL(uint32_t) RTDbgCfgRelease(RTDBGCFG hDbgCfg);
584
585/**
586 * Changes a property value by string.
587 *
588 * For string values the string is used more or less as given. For integer
589 * values and flags, it can contains both values (ORed together) or property
590 * specific mnemonics (ORed / ~ANDed).
591 *
592 * @returns IPRT status code.
593 * @retval VERR_DBG_CFG_INVALID_VALUE
594 * @param hDbgCfg The debugging configuration handle.
595 * @param enmProp The property to change.
596 * @param enmOp How to change the property.
597 * @param pszValue The property value to apply.
598 */
599RTDECL(int) RTDbgCfgChangeString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, const char *pszValue);
600
601/**
602 * Changes a property value by unsigned integer (64-bit).
603 *
604 * This can only be applied to integer and flag properties.
605 *
606 * @returns IPRT status code.
607 * @retval VERR_DBG_CFG_NOT_UINT_PROP
608 * @param hDbgCfg The debugging configuration handle.
609 * @param enmProp The property to change.
610 * @param enmOp How to change the property.
611 * @param uValue The property value to apply.
612 */
613RTDECL(int) RTDbgCfgChangeUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, uint64_t uValue);
614
615/**
616 * Query a property value as string.
617 *
618 * Integer and flags properties are returned as a list of mnemonics if possible,
619 * otherwise as simple hex values.
620 *
621 * @returns IPRT status code.
622 * @retval VERR_BUFFER_OVERFLOW if there isn't sufficient buffer space. Nothing
623 * is written.
624 * @param hDbgCfg The debugging configuration handle.
625 * @param enmProp The property to change.
626 * @param pszValue The output buffer.
627 * @param cbValue The size of the output buffer.
628 */
629RTDECL(int) RTDbgCfgQueryString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, char *pszValue, size_t cbValue);
630
631/**
632 * Query a property value as unsigned integer (64-bit).
633 *
634 * Only integer and flags properties can be queried this way.
635 *
636 * @returns IPRT status code.
637 * @retval VERR_DBG_CFG_NOT_UINT_PROP
638 * @param hDbgCfg The debugging configuration handle.
639 * @param enmProp The property to change.
640 * @param puValue Where to return the value.
641 */
642RTDECL(int) RTDbgCfgQueryUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, uint64_t *puValue);
643
644/**
645 * Log callback.
646 *
647 * @param hDbgCfg The debug config instance.
648 * @param iLevel The message level.
649 * @param pszMsg The message.
650 * @param pvUser User argument.
651 */
652typedef DECLCALLBACK(void) FNRTDBGCFGLOG(RTDBGCFG hDbgCfg, uint32_t iLevel, const char *pszMsg, void *pvUser);
653/** Pointer to a log callback. */
654typedef FNRTDBGCFGLOG *PFNRTDBGCFGLOG;
655
656/**
657 * Sets the log callback for the configuration.
658 *
659 * This will fail if there is already a log callback present, unless pfnCallback
660 * is NULL.
661 *
662 * @returns IPRT status code.
663 * @param hDbgCfg The debugging configuration handle.
664 * @param pfnCallback The callback function. NULL to unset.
665 * @param pvUser The user argument.
666 */
667RTDECL(int) RTDbgCfgSetLogCallback(RTDBGCFG hDbgCfg, PFNRTDBGCFGLOG pfnCallback, void *pvUser);
668
669/**
670 * Callback used by the RTDbgCfgOpen function to try out a file that was found.
671 *
672 * @returns On statuses other than VINF_CALLBACK_RETURN and
673 * VERR_CALLBACK_RETURN the search will continue till the end of the
674 * list. These status codes will not necessarily be propagated to the
675 * caller in any consistent manner.
676 * @retval VINF_CALLBACK_RETURN if successfully opened the file and it's time
677 * to return
678 * @retval VERR_CALLBACK_RETURN if we should stop searching immediately.
679 *
680 * @param hDbgCfg The debugging configuration handle.
681 * @param pszFilename The path to the file that should be tried out.
682 * @param pvUser1 First user parameter.
683 * @param pvUser2 Second user parameter.
684 */
685typedef DECLCALLBACK(int) FNRTDBGCFGOPEN(RTDBGCFG hDbgCfg, const char *pszFilename, void *pvUser1, void *pvUser2);
686/** Pointer to a open-file callback used to the RTDbgCfgOpen functions. */
687typedef FNRTDBGCFGOPEN *PFNRTDBGCFGOPEN;
688
689
690RTDECL(int) RTDbgCfgOpenEx(RTDBGCFG hDbgCfg, const char *pszFilename, const char *pszCacheSubDir,
691 const char *pszUuidMappingSubDir, uint32_t fFlags,
692 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
693RTDECL(int) RTDbgCfgOpenPeImage(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
694 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
695RTDECL(int) RTDbgCfgOpenPdb70(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, uint32_t uAge,
696 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
697RTDECL(int) RTDbgCfgOpenPdb20(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, uint32_t uAge,
698 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
699RTDECL(int) RTDbgCfgOpenDbg(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
700 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
701RTDECL(int) RTDbgCfgOpenDwo(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t uCrc32,
702 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
703RTDECL(int) RTDbgCfgOpenDsymBundle(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid,
704 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
705RTDECL(int) RTDbgCfgOpenMachOImage(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid,
706 PFNRTDBGCFGOPEN pfnCallback, void *pvUser1, void *pvUser2);
707
708/** @name RTDBGCFG_O_XXX - Open flags for RTDbgCfgOpen.
709 * @{ */
710/** The operative system mask. The values are RT_OPSYS_XXX. */
711#define RTDBGCFG_O_OPSYS_MASK UINT32_C(0x000000ff)
712/** Same as RTDBGCFG_FLAGS_NO_SYSTEM_PATHS. */
713#define RTDBGCFG_O_NO_SYSTEM_PATHS RT_BIT_32(25)
714/** The files may be compressed MS styled. */
715#define RTDBGCFG_O_MAYBE_COMPRESSED_MS RT_BIT_32(26)
716/** Whether to make a recursive search. */
717#define RTDBGCFG_O_RECURSIVE RT_BIT_32(27)
718/** We're looking for a separate debug file. */
719#define RTDBGCFG_O_EXT_DEBUG_FILE RT_BIT_32(28)
720/** We're looking for an executable image. */
721#define RTDBGCFG_O_EXECUTABLE_IMAGE RT_BIT_32(29)
722/** The file search should be done in an case insensitive fashion. */
723#define RTDBGCFG_O_CASE_INSENSITIVE RT_BIT_32(30)
724/** Use Windbg style symbol servers when encountered in the path. */
725#define RTDBGCFG_O_SYMSRV RT_BIT_32(31)
726/** Mask of valid flags. */
727#define RTDBGCFG_O_VALID_MASK UINT32_C(0xfe0000ff)
728/** @} */
729
730
731/** @name Static symbol cache configuration
732 * @{ */
733/** The cache subdirectory containing the UUID mappings for .dSYM bundles.
734 * The UUID mappings implemented by IPRT are splitting the image/dsym UUID up
735 * into five 4 digit parts that maps to directories and one twelve digit part
736 * that maps to a symbolic link. The symlink points to the file in the
737 * Contents/Resources/DWARF/ directory of the .dSYM bundle for a .dSYM map, and
738 * to the image file (Contents/MacOS/bundlename for bundles) for image map.
739 *
740 * According to available documentation, both lldb and gdb are able to use these
741 * UUID maps to find debug info while debugging. See:
742 * http://lldb.llvm.org/symbols.html
743 */
744#define RTDBG_CACHE_UUID_MAP_DIR_DSYMS "dsym-uuids"
745/** The cache subdirectory containing the UUID mappings for image files. */
746#define RTDBG_CACHE_UUID_MAP_DIR_IMAGES "image-uuids"
747/** Suffix used for the cached .dSYM debug files.
748 * In .dSYM bundles only the .dSYM/Contents/Resources/DWARF/debug-file is
749 * copied into the cache, and in order to not clash with the stripped/rich image
750 * file, the cache tool slaps this suffix onto the name. */
751#define RTDBG_CACHE_DSYM_FILE_SUFFIX ".dwarf"
752/** @} */
753
754# endif /* IN_RING3 */
755
756/** @} */
757
758
759/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
760 * @{
761 */
762
763/**
764 * Creates an empty address space.
765 *
766 * @returns IPRT status code.
767 *
768 * @param phDbgAs Where to store the address space handle on success.
769 * @param FirstAddr The first address in the address space.
770 * @param LastAddr The last address in the address space.
771 * @param pszName The name of the address space.
772 */
773RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
774
775/**
776 * Variant of RTDbgAsCreate that takes a name format string.
777 *
778 * @returns IPRT status code.
779 *
780 * @param phDbgAs Where to store the address space handle on success.
781 * @param FirstAddr The first address in the address space.
782 * @param LastAddr The last address in the address space.
783 * @param pszNameFmt The name format of the address space.
784 * @param va Format arguments.
785 */
786RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr,
787 const char *pszNameFmt, va_list va) RT_IPRT_FORMAT_ATTR(4, 0);
788
789/**
790 * Variant of RTDbgAsCreate that takes a name format string.
791 *
792 * @returns IPRT status code.
793 *
794 * @param phDbgAs Where to store the address space handle on success.
795 * @param FirstAddr The first address in the address space.
796 * @param LastAddr The last address in the address space.
797 * @param pszNameFmt The name format of the address space.
798 * @param ... Format arguments.
799 */
800RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr,
801 const char *pszNameFmt, ...) RT_IPRT_FORMAT_ATTR(4, 5);
802
803/**
804 * Retains a reference to the address space.
805 *
806 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
807 *
808 * @param hDbgAs The address space handle.
809 *
810 * @remarks Will not take any locks.
811 */
812RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
813
814/**
815 * Release a reference to the address space.
816 *
817 * When the reference count reaches zero, the address space is destroyed.
818 * That means unlinking all the modules it currently contains, potentially
819 * causing some or all of them to be destroyed as they are managed by
820 * reference counting.
821 *
822 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
823 *
824 * @param hDbgAs The address space handle. The NIL handle is quietly
825 * ignored and 0 is returned.
826 *
827 * @remarks Will not take any locks.
828 */
829RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
830
831/**
832 * Locks the address space for exclusive access.
833 *
834 * @returns IRPT status code
835 * @param hDbgAs The address space handle.
836 */
837RTDECL(int) RTDbgAsLockExcl(RTDBGAS hDbgAs);
838
839/**
840 * Counters the actions of one RTDbgAsUnlockExcl call.
841 *
842 * @returns IRPT status code
843 * @param hDbgAs The address space handle.
844 */
845RTDECL(int) RTDbgAsUnlockExcl(RTDBGAS hDbgAs);
846
847/**
848 * Gets the name of an address space.
849 *
850 * @returns read only address space name.
851 * NULL if hDbgAs is invalid.
852 *
853 * @param hDbgAs The address space handle.
854 *
855 * @remarks Will not take any locks.
856 */
857RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
858
859/**
860 * Gets the first address in an address space.
861 *
862 * @returns The address.
863 * 0 if hDbgAs is invalid.
864 *
865 * @param hDbgAs The address space handle.
866 *
867 * @remarks Will not take any locks.
868 */
869RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
870
871/**
872 * Gets the last address in an address space.
873 *
874 * @returns The address.
875 * 0 if hDbgAs is invalid.
876 *
877 * @param hDbgAs The address space handle.
878 *
879 * @remarks Will not take any locks.
880 */
881RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
882
883/**
884 * Gets the number of modules in the address space.
885 *
886 * This can be used together with RTDbgAsModuleByIndex
887 * to enumerate the modules.
888 *
889 * @returns The number of modules.
890 *
891 * @param hDbgAs The address space handle.
892 *
893 * @remarks Will not take any locks.
894 */
895RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
896
897/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
898 * @{ */
899/** Replace all conflicting module.
900 * (The conflicting modules will be removed the address space and their
901 * references released.) */
902#define RTDBGASLINK_FLAGS_REPLACE RT_BIT_32(0)
903/** Mask containing the valid flags. */
904#define RTDBGASLINK_FLAGS_VALID_MASK UINT32_C(0x00000001)
905/** @} */
906
907/**
908 * Links a module into the address space at the give address.
909 *
910 * The size of the mapping is determined using RTDbgModImageSize().
911 *
912 * @returns IPRT status code.
913 * @retval VERR_OUT_OF_RANGE if the specified address will put the module
914 * outside the address space.
915 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
916 *
917 * @param hDbgAs The address space handle.
918 * @param hDbgMod The module handle of the module to be linked in.
919 * @param ImageAddr The address to link the module at.
920 * @param fFlags See RTDBGASLINK_FLAGS_*.
921 */
922RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
923
924/**
925 * Links a segment into the address space at the give address.
926 *
927 * The size of the mapping is determined using RTDbgModSegmentSize().
928 *
929 * @returns IPRT status code.
930 * @retval VERR_OUT_OF_RANGE if the specified address will put the module
931 * outside the address space.
932 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
933 *
934 * @param hDbgAs The address space handle.
935 * @param hDbgMod The module handle.
936 * @param iSeg The segment number (0-based) of the segment to be
937 * linked in.
938 * @param SegAddr The address to link the segment at.
939 * @param fFlags See RTDBGASLINK_FLAGS_*.
940 */
941RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
942
943/**
944 * Unlinks all the mappings of a module from the address space.
945 *
946 * @returns IPRT status code.
947 * @retval VERR_NOT_FOUND if the module wasn't found.
948 *
949 * @param hDbgAs The address space handle.
950 * @param hDbgMod The module handle of the module to be unlinked.
951 */
952RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
953
954/**
955 * Unlinks the mapping at the specified address.
956 *
957 * @returns IPRT status code.
958 * @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
959 *
960 * @param hDbgAs The address space handle.
961 * @param Addr The address within the mapping to be unlinked.
962 */
963RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
964
965/**
966 * Get a the handle of a module in the address space by is index.
967 *
968 * @returns A retained handle to the specified module. The caller must release
969 * the returned reference.
970 * NIL_RTDBGMOD if invalid index or handle.
971 *
972 * @param hDbgAs The address space handle.
973 * @param iModule The index of the module to get.
974 *
975 * @remarks The module indexes may change after calls to RTDbgAsModuleLink,
976 * RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
977 * RTDbgAsModuleUnlinkByAddr.
978 */
979RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
980
981/**
982 * Queries mapping module information by handle.
983 *
984 * @returns IPRT status code.
985 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.
986 *
987 * @param hDbgAs The address space handle.
988 * @param Addr Address within the mapping of the module or segment.
989 * @param phMod Where to the return the retained module handle.
990 * Optional.
991 * @param pAddr Where to return the base address of the mapping.
992 * Optional.
993 * @param piSeg Where to return the segment index. This is set to
994 * NIL if the entire module is mapped as a single
995 * mapping. Optional.
996 */
997RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
998
999/**
1000 * Queries mapping module information by name.
1001 *
1002 * @returns IPRT status code.
1003 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.
1004 * @retval VERR_OUT_OF_RANGE if the name index was out of range.
1005 *
1006 * @param hDbgAs The address space handle.
1007 * @param pszName The module name.
1008 * @param iName There can be more than one module by the same name
1009 * in an address space. This argument indicates which
1010 * is meant. (0 based)
1011 * @param phMod Where to the return the retained module handle.
1012 */
1013RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
1014
1015/**
1016 * Information about a mapping.
1017 *
1018 * This is used by RTDbgAsModuleGetMapByIndex.
1019 */
1020typedef struct RTDBGASMAPINFO
1021{
1022 /** The mapping address. */
1023 RTUINTPTR Address;
1024 /** The segment mapped there.
1025 * This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */
1026 RTDBGSEGIDX iSeg;
1027} RTDBGASMAPINFO;
1028/** Pointer to info about an address space mapping. */
1029typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
1030/** Pointer to const info about an address space mapping. */
1031typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO;
1032
1033/**
1034 * Queries mapping information for a module given by index.
1035 *
1036 * @returns IRPT status code.
1037 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1038 * @retval VERR_OUT_OF_RANGE if the name index was out of range.
1039 * @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned
1040 * information is incomplete.
1041 *
1042 * @param hDbgAs The address space handle.
1043 * @param iModule The index of the module to get.
1044 * @param paMappings Where to return the mapping information. The buffer
1045 * size is given by *pcMappings.
1046 * @param pcMappings IN: Size of the paMappings array. OUT: The number of
1047 * entries returned.
1048 * @param fFlags Flags for reserved for future use. MBZ.
1049 *
1050 * @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
1051 * iModule parameter.
1052 */
1053RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags);
1054
1055/**
1056 * Adds a symbol to a module in the address space.
1057 *
1058 * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
1059 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1060 * @retval VERR_NOT_FOUND if no module was found at the specified address.
1061 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1062 * custom symbols.
1063 *
1064 * @param hDbgAs The address space handle.
1065 * @param pszSymbol The symbol name.
1066 * @param Addr The address of the symbol.
1067 * @param cb The size of the symbol.
1068 * @param fFlags Symbol flags, RTDBGSYMBOLADD_F_XXX.
1069 * @param piOrdinal Where to return the symbol ordinal on success. If
1070 * the interpreter doesn't do ordinals, this will be set to
1071 * UINT32_MAX. Optional
1072 */
1073RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char *pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
1074
1075/**
1076 * Query a symbol by address.
1077 *
1078 * @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
1079 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1080 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
1081 * @retval VERR_INVALID_PARAMETER if incorrect flags.
1082 *
1083 * @param hDbgAs The address space handle.
1084 * @param Addr The address which closest symbol is requested.
1085 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1086 * @param poffDisp Where to return the distance between the symbol
1087 * and address. Optional.
1088 * @param pSymbol Where to return the symbol info.
1089 * @param phMod Where to return the module handle. Optional.
1090 */
1091RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
1092 PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
1093
1094/**
1095 * Query a symbol by address.
1096 *
1097 * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
1098 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1099 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
1100 * @retval VERR_INVALID_PARAMETER if incorrect flags.
1101 *
1102 * @param hDbgAs The address space handle.
1103 * @param Addr The address which closest symbol is requested.
1104 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1105 * @param poffDisp Where to return the distance between the symbol
1106 * and address. Optional.
1107 * @param ppSymInfo Where to return the pointer to the allocated symbol
1108 * info. Always set. Free with RTDbgSymbolFree.
1109 * @param phMod Where to return the module handle. Optional.
1110 */
1111RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
1112 PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod);
1113
1114/**
1115 * Query a symbol by name.
1116 *
1117 * @returns IPRT status code.
1118 * @retval VERR_SYMBOL_NOT_FOUND if not found.
1119 *
1120 * @param hDbgAs The address space handle.
1121 * @param pszSymbol The symbol name. It is possible to limit the scope
1122 * of the search by prefixing the symbol with a module
1123 * name pattern followed by a bang (!) character.
1124 * RTStrSimplePatternNMatch is used for the matching.
1125 * @param pSymbol Where to return the symbol info.
1126 * @param phMod Where to return the module handle. Optional.
1127 */
1128RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
1129
1130/**
1131 * Query a symbol by name, allocating the returned symbol structure.
1132 *
1133 * @returns IPRT status code.
1134 * @retval VERR_SYMBOL_NOT_FOUND if not found.
1135 *
1136 * @param hDbgAs The address space handle.
1137 * @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.
1138 * @param ppSymbol Where to return the pointer to the allocated
1139 * symbol info. Always set. Free with RTDbgSymbolFree.
1140 * @param phMod Where to return the module handle. Optional.
1141 */
1142RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol, PRTDBGMOD phMod);
1143
1144/**
1145 * Adds a line number to a module in the address space.
1146 *
1147 * @returns IPRT status code. See RTDbgModLineAdd for more specific ones.
1148 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1149 * @retval VERR_NOT_FOUND if no module was found at the specified address.
1150 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1151 * custom symbols.
1152 *
1153 * @param hDbgAs The address space handle.
1154 * @param pszFile The file name.
1155 * @param uLineNo The line number.
1156 * @param Addr The address of the symbol.
1157 * @param piOrdinal Where to return the line number ordinal on success.
1158 * If the interpreter doesn't do ordinals, this will be
1159 * set to UINT32_MAX. Optional.
1160 */
1161RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char *pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t *piOrdinal);
1162
1163/**
1164 * Query a line number by address.
1165 *
1166 * @returns IPRT status code. See RTDbgModLineAddrA for more specific ones.
1167 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1168 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
1169 *
1170 * @param hDbgAs The address space handle.
1171 * @param Addr The address which closest symbol is requested.
1172 * @param poffDisp Where to return the distance between the line
1173 * number and address.
1174 * @param pLine Where to return the line number information.
1175 * @param phMod Where to return the module handle. Optional.
1176 */
1177RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine, PRTDBGMOD phMod);
1178
1179/**
1180 * Query a line number by address.
1181 *
1182 * @returns IPRT status code. See RTDbgModLineAddrA for more specific ones.
1183 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
1184 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
1185 *
1186 * @param hDbgAs The address space handle.
1187 * @param Addr The address which closest symbol is requested.
1188 * @param poffDisp Where to return the distance between the line
1189 * number and address.
1190 * @param ppLine Where to return the pointer to the allocated line
1191 * number info. Always set. Free with RTDbgLineFree.
1192 * @param phMod Where to return the module handle. Optional.
1193 */
1194RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine, PRTDBGMOD phMod);
1195
1196/** @todo Missing some bits here. */
1197
1198/** @} */
1199
1200
1201# ifdef IN_RING3
1202/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
1203 * @{
1204 */
1205
1206/**
1207 * Creates a module based on the default debug info container.
1208 *
1209 * This can be used to manually load a module and its symbol. The primary user
1210 * group is the debug info interpreters, which use this API to create an
1211 * efficient debug info container behind the scenes and forward all queries to
1212 * it once the info has been loaded.
1213 *
1214 * @returns IPRT status code.
1215 *
1216 * @param phDbgMod Where to return the module handle.
1217 * @param pszName The name of the module (mandatory).
1218 * @param cbSeg The size of initial segment. If zero, segments will
1219 * have to be added manually using RTDbgModSegmentAdd.
1220 * @param fFlags Flags reserved for future extensions, MBZ for now.
1221 */
1222RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
1223
1224RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName,
1225 RTLDRARCH enmArch, RTDBGCFG hDbgCfg);
1226RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, RTUINTPTR uSubtrahend,
1227 RTDBGCFG hDbgCfg);
1228RTDECL(int) RTDbgModCreateFromPeImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName,
1229 PRTLDRMOD phLdrMod, uint32_t cbImage, uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
1230RTDECL(int) RTDbgModCreateFromDbg(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage,
1231 uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
1232RTDECL(int) RTDbgModCreateFromPdb(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage,
1233 PCRTUUID pUuid, uint32_t Age, RTDBGCFG hDbgCfg);
1234RTDECL(int) RTDbgModCreateFromDwo(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName, uint32_t cbImage,
1235 uint32_t uCrc32, RTDBGCFG hDbgCfg);
1236RTDECL(int) RTDbgModCreateFromMachOImage(PRTDBGMOD phDbgMod, const char *pszFilename, const char *pszName,
1237 RTLDRARCH enmArch, uint32_t cbImage, uint32_t cSegs, PCRTDBGSEGMENT paSegs,
1238 PCRTUUID pUuid, RTDBGCFG hDbgCfg, uint32_t fFlags);
1239
1240/** @name Flags for RTDbgModCreate and friends.
1241 * @{ */
1242/** Overrides the hDbgCfg settings and forces an image and/or symbol file
1243 * search. RTDbgModCreate will quietly ignore this flag. */
1244#define RTDBGMOD_F_NOT_DEFERRED RT_BIT_32(0)
1245/** @} */
1246
1247
1248/**
1249 * Retains another reference to the module.
1250 *
1251 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
1252 *
1253 * @param hDbgMod The module handle.
1254 *
1255 * @remarks Will not take any locks.
1256 */
1257RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
1258
1259/**
1260 * Release a reference to the module.
1261 *
1262 * When the reference count reaches zero, the module is destroyed.
1263 *
1264 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
1265 *
1266 * @param hDbgMod The module handle. The NIL handle is quietly ignored
1267 * and 0 is returned.
1268 *
1269 * @remarks Will not take any locks.
1270 */
1271RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
1272
1273/**
1274 * Removes all content from the debug module (container), optionally only
1275 * leaving segments and image size intact.
1276 *
1277 * This is only possible on container modules, i.e. created by RTDbgModCreate().
1278 *
1279 * @returns IPRT status code.
1280 * @param hDbgMod The module handle.
1281 * @param fLeaveSegments Whether to leave segments (and image size) as is.
1282 */
1283RTDECL(int) RTDbgModRemoveAll(RTDBGMOD hDbgMod, bool fLeaveSegments);
1284
1285/**
1286 * Gets the module name.
1287 *
1288 * @returns Pointer to a read only string containing the name.
1289 *
1290 * @param hDbgMod The module handle.
1291 */
1292RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
1293
1294/**
1295 * Gets the name of the debug info file we're using.
1296 *
1297 * @returns Pointer to a read only string containing the filename, NULL if we
1298 * don't use one.
1299 *
1300 * @param hDbgMod The module handle.
1301 */
1302RTDECL(const char *) RTDbgModDebugFile(RTDBGMOD hDbgMod);
1303
1304/**
1305 * Gets the image filename (as specified by the user).
1306 *
1307 * @returns Pointer to a read only string containing the filename.
1308 *
1309 * @param hDbgMod The module handle.
1310 */
1311RTDECL(const char *) RTDbgModImageFile(RTDBGMOD hDbgMod);
1312
1313/**
1314 * Gets the image filename actually used if it differs from RTDbgModImageFile.
1315 *
1316 * @returns Pointer to a read only string containing the filename, NULL if same
1317 * as RTDBgModImageFile.
1318 *
1319 * @param hDbgMod The module handle.
1320 */
1321RTDECL(const char *) RTDbgModImageFileUsed(RTDBGMOD hDbgMod);
1322
1323/**
1324 * Checks if the loading of the debug info has been postponed.
1325 *
1326 * @returns true if postponed, false if not or invalid handle.
1327 * @param hDbgMod The module handle.
1328 */
1329RTDECL(bool) RTDbgModIsDeferred(RTDBGMOD hDbgMod);
1330
1331/**
1332 * Checks if the debug info is exports only.
1333 *
1334 * @returns true if exports only, false if not or invalid handle.
1335 * @param hDbgMod The module handle.
1336 */
1337RTDECL(bool) RTDbgModIsExports(RTDBGMOD hDbgMod);
1338
1339/**
1340 * Converts an image relative address to a segment:offset address.
1341 *
1342 * @returns Segment index on success.
1343 * NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
1344 * invalid.
1345 *
1346 * @param hDbgMod The module handle.
1347 * @param uRva The image relative address to convert.
1348 * @param poffSeg Where to return the segment offset. Optional.
1349 */
1350RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
1351
1352/**
1353 * Gets the module tag value if any.
1354 *
1355 * @returns The tag. 0 if hDbgMod is invalid.
1356 *
1357 * @param hDbgMod The module handle.
1358 */
1359RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
1360
1361/**
1362 * Tags or untags the module.
1363 *
1364 * @returns IPRT status code.
1365 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1366 *
1367 * @param hDbgMod The module handle.
1368 * @param uTag The tag value. The convention is that 0 is no tag
1369 * and any other value means it's tagged. It's adviced
1370 * to use some kind of unique number like an address
1371 * (global or string cache for instance) to avoid
1372 * collisions with other users
1373 */
1374RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
1375
1376
1377/**
1378 * Image size when mapped if segments are mapped adjacently.
1379 *
1380 * For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
1381 * NE and such it's a bit odder and the answer may not make much sense for them.
1382 *
1383 * @returns Image mapped size.
1384 * RTUINTPTR_MAX is returned if the handle is invalid.
1385 *
1386 * @param hDbgMod The module handle.
1387 */
1388RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
1389
1390/**
1391 * Gets the image format.
1392 *
1393 * @returns Image format.
1394 * @retval RTLDRFMT_INVALID if the handle is invalid or if the format isn't known.
1395 * @param hDbgMod The debug module handle.
1396 * @sa RTLdrGetFormat
1397 */
1398RTDECL(RTLDRFMT) RTDbgModImageGetFormat(RTDBGMOD hDbgMod);
1399
1400/**
1401 * Gets the image architecture.
1402 *
1403 * @returns Image architecture.
1404 * @retval RTLDRARCH_INVALID if the handle is invalid.
1405 * @retval RTLDRARCH_WHATEVER if unknown.
1406 * @param hDbgMod The debug module handle.
1407 * @sa RTLdrGetArch
1408 */
1409RTDECL(RTLDRARCH) RTDbgModImageGetArch(RTDBGMOD hDbgMod);
1410
1411/**
1412 * Generic method for querying image properties.
1413 *
1414 * @returns IPRT status code.
1415 * @retval VERR_NOT_SUPPORTED if the property query isn't supported (either all
1416 * or that specific property). The caller must handle this result.
1417 * @retval VERR_NOT_FOUND the property was not found in the module. The caller
1418 * must also normally deal with this.
1419 * @retval VERR_INVALID_FUNCTION if the function value is wrong.
1420 * @retval VERR_INVALID_PARAMETER if the fixed buffer size is wrong. Correct
1421 * size in @a *pcbRet.
1422 * @retval VERR_BUFFER_OVERFLOW if the function doesn't have a fixed size
1423 * buffer and the buffer isn't big enough. Correct size in @a *pcbRet.
1424 * @retval VERR_INVALID_HANDLE if the handle is invalid.
1425 *
1426 * @param hDbgMod The debug module handle.
1427 * @param enmProp The property to query.
1428 * @param pvBuf Pointer to the input / output buffer. In most cases
1429 * it's only used for returning data.
1430 * @param cbBuf The size of the buffer.
1431 * @param pcbRet Where to return the amount of data returned. On
1432 * buffer size errors, this is set to the correct size.
1433 * Optional.
1434 * @sa RTLdrQueryPropEx
1435 */
1436RTDECL(int) RTDbgModImageQueryProp(RTDBGMOD hDbgMod, RTLDRPROP enmProp, void *pvBuf, size_t cbBuf, size_t *pcbRet);
1437
1438
1439/**
1440 * Adds a segment to the module. Optional feature.
1441 *
1442 * This method is intended used for manually constructing debug info for a
1443 * module. The main usage is from other debug info interpreters that want to
1444 * avoid writing a debug info database and instead uses the standard container
1445 * behind the scenes.
1446 *
1447 * @returns IPRT status code.
1448 * @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
1449 * interpreter. This is a common return code.
1450 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1451 * @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
1452 * @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
1453 * @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
1454 * @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
1455 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
1456 *
1457 * @param hDbgMod The module handle.
1458 * @param uRva The image relative address of the segment.
1459 * @param cb The size of the segment.
1460 * @param pszName The segment name. Does not normally need to be
1461 * unique, although this is somewhat up to the
1462 * debug interpreter to decide.
1463 * @param fFlags Segment flags. Reserved for future used, MBZ.
1464 * @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
1465 * The assigned segment index on successful return.
1466 * Optional.
1467 */
1468RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
1469 uint32_t fFlags, PRTDBGSEGIDX piSeg);
1470
1471/**
1472 * Gets the number of segments in the module.
1473 *
1474 * This is can be used to determine the range which can be passed to
1475 * RTDbgModSegmentByIndex and derivates.
1476 *
1477 * @returns The segment relative address.
1478 * NIL_RTDBGSEGIDX if the handle is invalid.
1479 *
1480 * @param hDbgMod The module handle.
1481 */
1482RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
1483
1484/**
1485 * Query information about a segment.
1486 *
1487 * This can be used together with RTDbgModSegmentCount to enumerate segments.
1488 * The index starts a 0 and stops one below RTDbgModSegmentCount.
1489 *
1490 * @returns IPRT status code.
1491 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
1492 * @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
1493 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1494 *
1495 * @param hDbgMod The module handle.
1496 * @param iSeg The segment index. No special segments.
1497 * @param pSegInfo Where to return the segment info. The
1498 * RTDBGSEGMENT::Address member will be set to
1499 * RTUINTPTR_MAX or the load address used at link time.
1500 */
1501RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
1502
1503/**
1504 * Gets the size of a segment.
1505 *
1506 * This is a just a wrapper around RTDbgModSegmentByIndex.
1507 *
1508 * @returns The segment size.
1509 * RTUINTPTR_MAX is returned if either the handle and segment index are
1510 * invalid.
1511 *
1512 * @param hDbgMod The module handle.
1513 * @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
1514 * If RTDBGSEGIDX_RVA is used, the functions returns
1515 * the same value as RTDbgModImageSize.
1516 */
1517RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1518
1519/**
1520 * Gets the image relative address of a segment.
1521 *
1522 * This is a just a wrapper around RTDbgModSegmentByIndex.
1523 *
1524 * @returns The segment relative address.
1525 * RTUINTPTR_MAX is returned if either the handle and segment index are
1526 * invalid.
1527 *
1528 * @param hDbgMod The module handle.
1529 * @param iSeg The segment index. No special segment indexes
1530 * allowed (asserted).
1531 */
1532RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1533
1534
1535/**
1536 * Adds a line number to the module.
1537 *
1538 * @returns IPRT status code.
1539 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1540 * custom symbols. This is a common place occurrence.
1541 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1542 * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1543 * short.
1544 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1545 * it's not inside any of the segments defined by the module.
1546 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1547 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1548 * end of the segment.
1549 * @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
1550 * @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
1551 * @retval VERR_DBG_DUPLICATE_SYMBOL
1552 * @retval VERR_DBG_ADDRESS_CONFLICT
1553 *
1554 * @param hDbgMod The module handle.
1555 * @param pszSymbol The symbol name.
1556 * @param iSeg The segment index.
1557 * @param off The segment offset.
1558 * @param cb The size of the symbol. Can be zero, although this
1559 * may depend somewhat on the debug interpreter.
1560 * @param fFlags Symbol flags, RTDBGSYMBOLADD_F_XXX.
1561 * @param piOrdinal Where to return the symbol ordinal on success. If
1562 * the interpreter doesn't do ordinals, this will be set to
1563 * UINT32_MAX. Optional.
1564 */
1565RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
1566 RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
1567
1568/**
1569 * Gets the symbol count.
1570 *
1571 * This can be used together wtih RTDbgModSymbolByOrdinal or
1572 * RTDbgModSymbolByOrdinalA to enumerate all the symbols.
1573 *
1574 * @returns The number of symbols in the module.
1575 * UINT32_MAX is returned if the module handle is invalid or some other
1576 * error occurs.
1577 *
1578 * @param hDbgMod The module handle.
1579 */
1580RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
1581
1582/**
1583 * Queries symbol information by ordinal number.
1584 *
1585 * @returns IPRT status code.
1586 * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1587 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1588 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1589 * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1590 *
1591 * @param hDbgMod The module handle.
1592 * @param iOrdinal The symbol ordinal number. 0-based. The highest
1593 * number is RTDbgModSymbolCount() - 1.
1594 * @param pSymInfo Where to store the symbol information.
1595 */
1596RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
1597
1598/**
1599 * Queries symbol information by ordinal number.
1600 *
1601 * @returns IPRT status code.
1602 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1603 * @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1604 * @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1605 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1606 *
1607 * @param hDbgMod The module handle.
1608 * @param iOrdinal The symbol ordinal number. 0-based. The highest
1609 * number is RTDbgModSymbolCount() - 1.
1610 * @param ppSymInfo Where to store the pointer to the returned
1611 * symbol information. Always set. Free with
1612 * RTDbgSymbolFree.
1613 */
1614RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
1615
1616/**
1617 * Queries symbol information by address.
1618 *
1619 * The returned symbol is what the debug info interpreter considers the symbol
1620 * most applicable to the specified address. This usually means a symbol with an
1621 * address equal or lower than the requested.
1622 *
1623 * @returns IPRT status code.
1624 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1625 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1626 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1627 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1628 * it's not inside any of the segments defined by the module.
1629 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1630 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1631 * end of the segment.
1632 * @retval VERR_INVALID_PARAMETER if incorrect flags.
1633 *
1634 * @param hDbgMod The module handle.
1635 * @param iSeg The segment number.
1636 * @param off The offset into the segment.
1637 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1638 * @param poffDisp Where to store the distance between the
1639 * specified address and the returned symbol.
1640 * Optional.
1641 * @param pSymInfo Where to store the symbol information.
1642 */
1643RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1644 PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
1645
1646/**
1647 * Queries symbol information by address.
1648 *
1649 * The returned symbol is what the debug info interpreter considers the symbol
1650 * most applicable to the specified address. This usually means a symbol with an
1651 * address equal or lower than the requested.
1652 *
1653 * @returns IPRT status code.
1654 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1655 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1656 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1657 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1658 * it's not inside any of the segments defined by the module.
1659 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1660 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1661 * end of the segment.
1662 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1663 * @retval VERR_INVALID_PARAMETER if incorrect flags.
1664 *
1665 * @param hDbgMod The module handle.
1666 * @param iSeg The segment index.
1667 * @param off The offset into the segment.
1668 * @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1669 * @param poffDisp Where to store the distance between the
1670 * specified address and the returned symbol. Optional.
1671 * @param ppSymInfo Where to store the pointer to the returned
1672 * symbol information. Always set. Free with
1673 * RTDbgSymbolFree.
1674 */
1675RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1676 PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
1677
1678/**
1679 * Queries symbol information by symbol name.
1680 *
1681 * @returns IPRT status code.
1682 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1683 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1684 * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1685 * short.
1686 *
1687 * @param hDbgMod The module handle.
1688 * @param pszSymbol The symbol name.
1689 * @param pSymInfo Where to store the symbol information.
1690 */
1691RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
1692
1693/**
1694 * Queries symbol information by symbol name.
1695 *
1696 * @returns IPRT status code.
1697 * @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1698 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1699 * @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1700 * short.
1701 * @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1702 *
1703 * @param hDbgMod The module handle.
1704 * @param pszSymbol The symbol name.
1705 * @param ppSymInfo Where to store the pointer to the returned
1706 * symbol information. Always set. Free with
1707 * RTDbgSymbolFree.
1708 */
1709RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL *ppSymInfo);
1710
1711/**
1712 * Adds a line number to the module.
1713 *
1714 * @returns IPRT status code.
1715 * @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1716 * custom symbols. This should be consider a normal response.
1717 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1718 * @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1719 * empty.
1720 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1721 * it's not inside any of the segments defined by the module.
1722 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1723 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1724 * end of the segment.
1725 * @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1726 *
1727 * @param hDbgMod The module handle.
1728 * @param pszFile The file name.
1729 * @param uLineNo The line number.
1730 * @param iSeg The segment index.
1731 * @param off The segment offset.
1732 * @param piOrdinal Where to return the line number ordinal on
1733 * success. If the interpreter doesn't do ordinals,
1734 * this will be set to UINT32_MAX. Optional.
1735 */
1736RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1737 RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1738
1739/**
1740 * Gets the line number count.
1741 *
1742 * This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1743 * to enumerate all the line number information.
1744 *
1745 * @returns The number of line numbers in the module.
1746 * UINT32_MAX is returned if the module handle is invalid or some other
1747 * error occurs.
1748 *
1749 * @param hDbgMod The module handle.
1750 */
1751RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1752
1753/**
1754 * Queries line number information by ordinal number.
1755 *
1756 * This can be used to enumerate the line numbers for the module. Use
1757 * RTDbgModLineCount() to figure the end of the ordinals.
1758 *
1759 * @returns IPRT status code.
1760 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1761 * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1762 * ordinal.
1763 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1764
1765 * @param hDbgMod The module handle.
1766 * @param iOrdinal The line number ordinal number.
1767 * @param pLineInfo Where to store the information about the line
1768 * number.
1769 */
1770RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1771
1772/**
1773 * Queries line number information by ordinal number.
1774 *
1775 * This can be used to enumerate the line numbers for the module. Use
1776 * RTDbgModLineCount() to figure the end of the ordinals.
1777 *
1778 * @returns IPRT status code.
1779 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1780 * @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1781 * ordinal.
1782 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1783 * @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1784 *
1785 * @param hDbgMod The module handle.
1786 * @param iOrdinal The line number ordinal number.
1787 * @param ppLineInfo Where to store the pointer to the returned line
1788 * number information. Always set. Free with
1789 * RTDbgLineFree.
1790 */
1791RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1792
1793/**
1794 * Queries line number information by address.
1795 *
1796 * The returned line number is what the debug info interpreter considers the
1797 * one most applicable to the specified address. This usually means a line
1798 * number with an address equal or lower than the requested.
1799 *
1800 * @returns IPRT status code.
1801 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1802 * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1803 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1804 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1805 * it's not inside any of the segments defined by the module.
1806 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1807 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1808 * end of the segment.
1809 *
1810 * @param hDbgMod The module handle.
1811 * @param iSeg The segment number.
1812 * @param off The offset into the segment.
1813 * @param poffDisp Where to store the distance between the
1814 * specified address and the returned symbol.
1815 * Optional.
1816 * @param pLineInfo Where to store the line number information.
1817 */
1818RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1819
1820/**
1821 * Queries line number information by address.
1822 *
1823 * The returned line number is what the debug info interpreter considers the
1824 * one most applicable to the specified address. This usually means a line
1825 * number with an address equal or lower than the requested.
1826 *
1827 * @returns IPRT status code.
1828 * @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1829 * @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1830 * @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1831 * @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1832 * it's not inside any of the segments defined by the module.
1833 * @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1834 * @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1835 * end of the segment.
1836 * @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1837 *
1838 * @param hDbgMod The module handle.
1839 * @param iSeg The segment number.
1840 * @param off The offset into the segment.
1841 * @param poffDisp Where to store the distance between the
1842 * specified address and the returned symbol.
1843 * Optional.
1844 * @param ppLineInfo Where to store the pointer to the returned line
1845 * number information. Always set. Free with
1846 * RTDbgLineFree.
1847 */
1848RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1849
1850/**
1851 * Try use unwind information to unwind one frame.
1852 *
1853 * @returns IPRT status code. Last informational status from stack reader callback.
1854 * @retval VERR_DBG_NO_UNWIND_INFO if the module contains no unwind information.
1855 * @retval VERR_DBG_UNWIND_INFO_NOT_FOUND if no unwind information was found
1856 * for the location given by iSeg:off.
1857 *
1858 * @param hDbgMod The module handle.
1859 * @param iSeg The segment number of the program counter.
1860 * @param off The offset into @a iSeg. Together with @a iSeg
1861 * this corresponds to the RTDBGUNWINDSTATE::uPc
1862 * value pointed to by @a pState.
1863 * @param pState The unwind state to work.
1864 *
1865 * @sa RTLdrUnwindFrame
1866 */
1867RTDECL(int) RTDbgModUnwindFrame(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTDBGUNWINDSTATE pState);
1868
1869/** @} */
1870# endif /* IN_RING3 */
1871
1872
1873
1874/** @name Kernel Debug Info API
1875 *
1876 * This is a specialized API for obtaining symbols and structure information
1877 * about the running kernel. It is relatively OS specific. Its purpose and
1878 * operation is doesn't map all that well onto RTDbgMod, so a few dedicated
1879 * functions was created for it.
1880 *
1881 * @{ */
1882
1883/** Handle to the kernel debug info. */
1884typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO;
1885/** Pointer to a kernel debug info handle. */
1886typedef RTDBGKRNLINFO *PRTDBGKRNLINFO;
1887/** Nil kernel debug info handle. */
1888#define NIL_RTDBGKRNLINFO ((RTDBGKRNLINFO)0)
1889
1890/**
1891 * Opens the kernel debug info.
1892 *
1893 * @returns IPRT status code. Can fail for any number of reasons.
1894 *
1895 * @param phKrnlInfo Where to return the kernel debug info handle on
1896 * success.
1897 * @param fFlags Flags reserved for future use. Must be zero.
1898 */
1899RTR0DECL(int) RTR0DbgKrnlInfoOpen(PRTDBGKRNLINFO phKrnlInfo, uint32_t fFlags);
1900
1901/**
1902 * Retains a reference to the kernel debug info handle.
1903 *
1904 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
1905 * @param hKrnlInfo The kernel info handle.
1906 */
1907RTR0DECL(uint32_t) RTR0DbgKrnlInfoRetain(RTDBGKRNLINFO hKrnlInfo);
1908
1909
1910/**
1911 * Releases a reference to the kernel debug info handle, destroying it when the
1912 * counter reaches zero.
1913 *
1914 * @returns New reference count, UINT32_MAX on invalid handle (asserted).
1915 * @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is
1916 * quietly ignored.
1917 */
1918RTR0DECL(uint32_t) RTR0DbgKrnlInfoRelease(RTDBGKRNLINFO hKrnlInfo);
1919
1920/**
1921 * Queries the offset (in bytes) of a member of a kernel structure.
1922 *
1923 * @returns IPRT status code.
1924 * @retval VINF_SUCCESS and offset at @a poffMember.
1925 * @retval VERR_NOT_FOUND if the structure or the member was not found.
1926 * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1927 * @retval VERR_INVALID_POINTER if any of the pointers are bad.
1928 *
1929 * @param hKrnlInfo The kernel info handle.
1930 * @param pszModule The name of the module to search, pass NULL to
1931 * search the default kernel module(s).
1932 * @param pszStructure The structure name.
1933 * @param pszMember The member name.
1934 * @param poffMember Where to return the offset.
1935 */
1936RTR0DECL(int) RTR0DbgKrnlInfoQueryMember(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszStructure,
1937 const char *pszMember, size_t *poffMember);
1938
1939
1940/**
1941 * Queries the value (usually the address) of a kernel symbol.
1942 *
1943 * This may go looking for the symbol in other modules, in which case it will
1944 * always check the kernel symbol table first.
1945 *
1946 * @returns IPRT status code.
1947 * @retval VINF_SUCCESS and value at @a ppvSymbol.
1948 * @retval VERR_SYMBOL_NOT_FOUND
1949 * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1950 * @retval VERR_INVALID_POINTER if any of the pointers are bad.
1951 *
1952 * @param hKrnlInfo The kernel info handle.
1953 * @param pszModule Reserved for future extensions. Pass NULL.
1954 * @param pszSymbol The C name of the symbol.
1955 * @param ppvSymbol Where to return the symbol value, passing NULL is
1956 * OK. This may be modified even on failure, in
1957 * particular, it will be set to NULL when
1958 * VERR_SYMBOL_NOT_FOUND is returned.
1959 *
1960 * @sa RTR0DbgKrnlInfoGetSymbol, RTLdrGetSymbol
1961 */
1962RTR0DECL(int) RTR0DbgKrnlInfoQuerySymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1963 const char *pszSymbol, void **ppvSymbol);
1964
1965/**
1966 * Wrapper around RTR0DbgKrnlInfoQuerySymbol that returns the symbol.
1967 *
1968 * @return Symbol address if found, NULL if not found or some invalid parameter
1969 * or something.
1970 * @param hKrnlInfo The kernel info handle.
1971 * @param pszModule Reserved for future extensions. Pass NULL.
1972 * @param pszSymbol The C name of the symbol.
1973 * @sa RTR0DbgKrnlInfoQuerySymbol, RTLdrGetSymbol
1974 */
1975RTR0DECL(void *) RTR0DbgKrnlInfoGetSymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule, const char *pszSymbol);
1976
1977/**
1978 * Queries the size (in bytes) of a kernel data type.
1979 *
1980 * @returns IPRT status code.
1981 * @retval VINF_SUCCESS and size at @a pcbType.
1982 * @retval VERR_NOT_FOUND if the type was not found.
1983 * @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1984 * @retval VERR_INVALID_POINTER if any of the pointers are bad.
1985 * @retval VERR_WRONG_TYPE if the type was not a valid data type (e.g. a
1986 * function)
1987 *
1988 * @param hKrnlInfo The kernel info handle.
1989 * @param pszModule The name of the module to search, pass NULL to
1990 * search the default kernel module(s).
1991 * @param pszType The type name.
1992 * @param pcbType Where to return the size of the type.
1993 */
1994RTR0DECL(int) RTR0DbgKrnlInfoQuerySize(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1995 const char *pszType, size_t *pcbType);
1996/** @} */
1997
1998/** @} */
1999
2000RT_C_DECLS_END
2001
2002#endif
2003
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette