dbg.h@ 73494

最後變更在這個檔案從73494是 73494,由 vboxsync 提交於 7 年前
IPRT: Added single stack frame unwind function to RTDbgMod and RTLdr, copying over the PoC from DBGFRStack.cpp. bugref:3897
屬性 svn:eol-style 設為 `native` 屬性 svn:keywords 設為 `Author Date Id Revision`
檔案大小: 75.3 KB

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

注意: 瀏覽 TracBrowser 來幫助您使用儲存庫瀏覽器

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

以其他格式下載: