dbg.h@ 95897

Last change on this file since 95897 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 79.2 KB

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

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

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

Download in other formats: