dbg.h@ 99196

Last change on this file since 99196 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 79.5 KB

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

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

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

Download in other formats: