dbg.h@ 73460

Last change on this file since 73460 was 73460, checked in by vboxsync, 6 years ago
IPRT,DBGF,Diggers: Moved DBGFRETURNTYPE and the unwind state structure to IPRT (dbg.h) in prep for debug module interface and more. Added stack unwind assist callback for the OS diggers so they can identify special stack frames and supply more info via the sure-register-value array and frame flags. Identify and decode NT/AMD64 trap frames.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 73.3 KB

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

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

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

Download in other formats: