VirtualBox

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

Last change on this file was 106061, checked in by vboxsync, 4 weeks ago

Copyright year updates by scm.

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