dbg.h@ 76417

Last change on this file since 76417 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
34	RT_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. */
44	typedef uint32_t RTDBGSEGIDX;
45	/** Pointer to a debug segment index. */
46	typedef RTDBGSEGIDX *PRTDBGSEGIDX;
47	/** Pointer to a const debug segment index. */
48	typedef 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	*/
99	typedef 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. */
117	typedef RTDBGSEGMENT *PRTDBGSEGMENT;
118	/** Pointer to a const debug module segment. */
119	typedef RTDBGSEGMENT const *PCRTDBGSEGMENT;
120
121
122	/**
123	* Return type.
124	*/
125	typedef 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	*/
163	DECLINLINE(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	*/
193	DECLINLINE(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	*/
210	typedef 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	*/
296	DECLINLINE(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	*/
309	DECLINLINE(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	*/
322	DECLINLINE(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	*/
335	typedef 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. */
356	typedef RTDBGSYMBOL *PRTDBGSYMBOL;
357	/** Pointer to const debug symbol. */
358	typedef 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	*/
366	RTDECL(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	*/
375	RTDECL(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	*/
382	RTDECL(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	*/
392	typedef 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. */
411	typedef RTDBGLINE *PRTDBGLINE;
412	/** Pointer to const debug line number. */
413	typedef 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	*/
420	RTDECL(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	*/
429	RTDECL(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	*/
436	RTDECL(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	*/
451	RTDECL(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. */
471	typedef struct RTDBGCFGINT *RTDBGCFG;
472	/** Pointer to a debugging configuration handle. */
473	typedef 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	*/
502	typedef 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	*/
529	typedef 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	*/
565	RTDECL(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	*/
574	RTDECL(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	*/
583	RTDECL(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	*/
599	RTDECL(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	*/
613	RTDECL(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	*/
629	RTDECL(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	*/
642	RTDECL(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	*/
652	typedef DECLCALLBACK(void) FNRTDBGCFGLOG(RTDBGCFG hDbgCfg, uint32_t iLevel, const char pszMsg, void pvUser);
653	/** Pointer to a log callback. */
654	typedef 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	*/
667	RTDECL(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	*/
685	typedef DECLCALLBACK(int) FNRTDBGCFGOPEN(RTDBGCFG hDbgCfg, const char pszFilename, void pvUser1, void *pvUser2);
686	/** Pointer to a open-file callback used to the RTDbgCfgOpen functions. */
687	typedef FNRTDBGCFGOPEN *PFNRTDBGCFGOPEN;
688
689
690	RTDECL(int) RTDbgCfgOpenEx(RTDBGCFG hDbgCfg, const char pszFilename, const char pszCacheSubDir,
691	const char *pszUuidMappingSubDir, uint32_t fFlags,
692	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
693	RTDECL(int) RTDbgCfgOpenPeImage(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
694	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
695	RTDECL(int) RTDbgCfgOpenPdb70(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, uint32_t uAge,
696	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
697	RTDECL(int) RTDbgCfgOpenPdb20(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, uint32_t uAge,
698	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
699	RTDECL(int) RTDbgCfgOpenDbg(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
700	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
701	RTDECL(int) RTDbgCfgOpenDwo(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t uCrc32,
702	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
703	RTDECL(int) RTDbgCfgOpenDsymBundle(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid,
704	PFNRTDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
705	RTDECL(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	*/
773	RTDECL(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	*/
786	RTDECL(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	*/
800	RTDECL(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	*/
812	RTDECL(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	*/
829	RTDECL(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	*/
837	RTDECL(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	*/
845	RTDECL(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	*/
857	RTDECL(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	*/
869	RTDECL(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	*/
881	RTDECL(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	*/
895	RTDECL(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	*/
922	RTDECL(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	*/
941	RTDECL(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	*/
952	RTDECL(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	*/
963	RTDECL(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	*/
979	RTDECL(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	*/
997	RTDECL(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	*/
1013	RTDECL(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	*/
1020	typedef 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. */
1029	typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
1030	/** Pointer to const info about an address space mapping. */
1031	typedef 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	*/
1053	RTDECL(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	*/
1073	RTDECL(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	*/
1091	RTDECL(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	*/
1111	RTDECL(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	*/
1128	RTDECL(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	*/
1142	RTDECL(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	*/
1161	RTDECL(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	*/
1177	RTDECL(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	*/
1194	RTDECL(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	*/
1222	RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
1223
1224	RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName,
1225	RTLDRARCH enmArch, RTDBGCFG hDbgCfg);
1226	RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR uSubtrahend,
1227	RTDBGCFG hDbgCfg);
1228	RTDECL(int) RTDbgModCreateFromPeImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName,
1229	PRTLDRMOD phLdrMod, uint32_t cbImage, uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
1230	RTDECL(int) RTDbgModCreateFromDbg(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
1231	uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
1232	RTDECL(int) RTDbgModCreateFromPdb(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
1233	PCRTUUID pUuid, uint32_t Age, RTDBGCFG hDbgCfg);
1234	RTDECL(int) RTDbgModCreateFromDwo(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
1235	uint32_t uCrc32, RTDBGCFG hDbgCfg);
1236	RTDECL(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	*/
1257	RTDECL(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	*/
1271	RTDECL(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	*/
1283	RTDECL(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	*/
1292	RTDECL(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	*/
1302	RTDECL(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	*/
1311	RTDECL(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	*/
1321	RTDECL(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	*/
1329	RTDECL(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	*/
1337	RTDECL(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	*/
1350	RTDECL(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	*/
1359	RTDECL(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	*/
1374	RTDECL(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	*/
1388	RTDECL(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	*/
1398	RTDECL(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	*/
1409	RTDECL(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	*/
1436	RTDECL(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	*/
1468	RTDECL(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	*/
1482	RTDECL(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	*/
1501	RTDECL(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	*/
1517	RTDECL(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	*/
1532	RTDECL(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	*/
1565	RTDECL(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	*/
1580	RTDECL(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	*/
1596	RTDECL(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	*/
1614	RTDECL(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	*/
1643	RTDECL(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	*/
1675	RTDECL(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	*/
1691	RTDECL(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	*/
1709	RTDECL(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	*/
1736	RTDECL(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	*/
1751	RTDECL(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	*/
1770	RTDECL(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	*/
1791	RTDECL(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	*/
1818	RTDECL(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	*/
1848	RTDECL(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	*/
1867	RTDECL(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. */
1884	typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO;
1885	/** Pointer to a kernel debug info handle. */
1886	typedef 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	*/
1899	RTR0DECL(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	*/
1907	RTR0DECL(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	*/
1918	RTR0DECL(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	*/
1936	RTR0DECL(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	*/
1962	RTR0DECL(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	*/
1975	RTR0DECL(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	*/
1994	RTR0DECL(int) RTR0DbgKrnlInfoQuerySize(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1995	const char pszType, size_t pcbType);
1996	/** @} */
1997
1998	/** @} */
1999
2000	RT_C_DECLS_END
2001
2002	#endif
2003

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

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

Download in other formats: