dbg.h@ 46157

Last change on this file since 46157 was 46134, checked in by vboxsync, 12 years ago
RTDbgModRemoveAll
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 62.3 KB

Line
1	/* $Id: dbg.h 46134 2013-05-16 23:32:06Z vboxsync $ */
2	/** @file
3	* IPRT - Debugging Routines.
4	*/
5
6	/*
7	* Copyright (C) 2008-2012 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
33	RT_C_DECLS_BEGIN
34
35	# ifdef IN_RING3
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	/** Mask of valid flags. */
73	#define RTDBGSYMADDR_FLAGS_VALID_MASK UINT32_C(1)
74	/** @} */
75
76
77	/** Max length (including '\\0') of a segment name. */
78	#define RTDBG_SEGMENT_NAME_LENGTH (128 - 8 - 8 - 8 - 4 - 4)
79
80	/**
81	* Debug module segment.
82	*/
83	typedef struct RTDBGSEGMENT
84	{
85	/** The load address.
86	* RTUINTPTR_MAX if not applicable. */
87	RTUINTPTR Address;
88	/** The image relative virtual address of the segment.
89	* RTUINTPTR_MAX if not applicable. */
90	RTUINTPTR uRva;
91	/** The segment size. */
92	RTUINTPTR cb;
93	/** The segment flags. (reserved) */
94	uint32_t fFlags;
95	/** The segment index. */
96	RTDBGSEGIDX iSeg;
97	/** Symbol name. */
98	char szName[RTDBG_SEGMENT_NAME_LENGTH];
99	} RTDBGSEGMENT;
100	/** Pointer to a debug module segment. */
101	typedef RTDBGSEGMENT *PRTDBGSEGMENT;
102	/** Pointer to a const debug module segment. */
103	typedef RTDBGSEGMENT const *PCRTDBGSEGMENT;
104
105
106
107	/** Max length (including '\\0') of a symbol name. */
108	#define RTDBG_SYMBOL_NAME_LENGTH (384 - 8 - 8 - 8 - 4 - 4 - 8)
109
110	/**
111	* Debug symbol.
112	*/
113	typedef struct RTDBGSYMBOL
114	{
115	/** Symbol value (address).
116	* This depends a bit who you ask. It will be the same as offSeg when you
117	* as RTDbgMod, but the mapping address if you ask RTDbgAs. */
118	RTUINTPTR Value;
119	/** Symbol size. */
120	RTUINTPTR cb;
121	/** Offset into the segment specified by iSeg. */
122	RTUINTPTR offSeg;
123	/** Segment number. */
124	RTDBGSEGIDX iSeg;
125	/** Symbol Flags. (reserved). */
126	uint32_t fFlags;
127	/** Symbol ordinal.
128	* This is set to UINT32_MAX if the ordinals aren't supported. */
129	uint32_t iOrdinal;
130	/** Symbol name. */
131	char szName[RTDBG_SYMBOL_NAME_LENGTH];
132	} RTDBGSYMBOL;
133	/** Pointer to debug symbol. */
134	typedef RTDBGSYMBOL *PRTDBGSYMBOL;
135	/** Pointer to const debug symbol. */
136	typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
137
138	/**
139	* Allocate a new symbol structure.
140	*
141	* @returns Pointer to a new structure on success, NULL on failure.
142	*/
143	RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void);
144
145	/**
146	* Duplicates a symbol structure.
147	*
148	* @returns Pointer to duplicate on success, NULL on failure.
149	*
150	* @param pSymInfo The symbol info to duplicate.
151	*/
152	RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymInfo);
153
154	/**
155	* Free a symbol structure previously allocated by a RTDbg method.
156	*
157	* @param pSymInfo The symbol info to free. NULL is ignored.
158	*/
159	RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymInfo);
160
161
162	/** Max length (including '\\0') of a debug info file name. */
163	#define RTDBG_FILE_NAME_LENGTH (260)
164
165
166	/**
167	* Debug line number information.
168	*/
169	typedef struct RTDBGLINE
170	{
171	/** Address.
172	* This depends a bit who you ask. It will be the same as offSeg when you
173	* as RTDbgMod, but the mapping address if you ask RTDbgAs. */
174	RTUINTPTR Address;
175	/** Offset into the segment specified by iSeg. */
176	RTUINTPTR offSeg;
177	/** Segment number. */
178	RTDBGSEGIDX iSeg;
179	/** Line number. */
180	uint32_t uLineNo;
181	/** Symbol ordinal.
182	* This is set to UINT32_MAX if the ordinals aren't supported. */
183	uint32_t iOrdinal;
184	/** Filename. */
185	char szFilename[RTDBG_FILE_NAME_LENGTH];
186	} RTDBGLINE;
187	/** Pointer to debug line number. */
188	typedef RTDBGLINE *PRTDBGLINE;
189	/** Pointer to const debug line number. */
190	typedef const RTDBGLINE *PCRTDBGLINE;
191
192	/**
193	* Allocate a new line number structure.
194	*
195	* @returns Pointer to a new structure on success, NULL on failure.
196	*/
197	RTDECL(PRTDBGLINE) RTDbgLineAlloc(void);
198
199	/**
200	* Duplicates a line number structure.
201	*
202	* @returns Pointer to duplicate on success, NULL on failure.
203	*
204	* @param pLine The line number to duplicate.
205	*/
206	RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);
207
208	/**
209	* Free a line number structure previously allocated by a RTDbg method.
210	*
211	* @param pLine The line number to free. NULL is ignored.
212	*/
213	RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine);
214
215
216	/** @defgroup grp_rt_dbgcfg RTDbgCfg - Debugging Configuration
217	*
218	* The settings used when loading and processing debug info is kept in a
219	* RTDBGCFG instance since it's generally shared for a whole debugging session
220	* and anyhow would be a major pain to pass as individual parameters to each
221	* call. The debugging config API not only keeps the settings information but
222	* also provide APIs for making use of it, and in some cases, like for instance
223	* symbol severs, retriving and maintaining it.
224	*
225	* @todo Work in progress - APIs are still missing, adding when needed.
226	*
227	* @{
228	*/
229
230	/** Debugging configuration handle. */
231	typedef struct RTDBGCFGINT *RTDBGCFG;
232	/** Pointer to a debugging configuration handle. */
233	typedef RTDBGCFG *PRTDBGCFG;
234	/** NIL debug configuration handle. */
235	#define NIL_RTDBGCFG ((RTDBGCFG)0)
236
237	/** @name RTDBGCFG_FLAGS_XXX - Debugging configuration flags.
238	* @{ */
239	/** Use deferred loading. */
240	#define RTDBGCFG_FLAGS_DEFERRED RT_BIT_64(0)
241	/** Don't use the symbol server (http). */
242	#define RTDBGCFG_FLAGS_NO_SYM_SRV RT_BIT_64(1)
243	/** Don't use system search paths.
244	* On windows this means not using _NT_ALT_SYMBOL_PATH, _NT_SYMBOL_PATH,
245	* _NT_SOURCE_PATH, and _NT_EXECUTABLE_PATH.
246	* On other systems the effect has yet to be determined. */
247	#define RTDBGCFG_FLAGS_NO_SYSTEM_PATHS RT_BIT_64(2)
248	/** Don't search the debug and image paths recursively. */
249	#define RTDBGCFG_FLAGS_NO_RECURSIV_SEARCH RT_BIT_64(3)
250	/** Don't search the source paths recursively. */
251	#define RTDBGCFG_FLAGS_NO_RECURSIV_SRC_SEARCH RT_BIT_64(4)
252	/** @} */
253
254	/**
255	* Debugging configuration properties.
256	*
257	* The search paths are using the DOS convention of semicolon as separator
258	* character. The the special 'srv' + asterisk syntax known from the windows
259	* debugger search paths are also supported to some extent, as is 'cache' +
260	* asterisk.
261	*/
262	typedef enum RTDBGCFGPROP
263	{
264	/** The customary invalid 0 value. */
265	RTDBGCFGPROP_INVALID = 0,
266	/** RTDBGCFG_FLAGS_XXX.
267	* Env: _FLAGS
268	* The environment variable can be specified as a unsigned value or one or more
269	* mnemonics separated by spaces. */
270	RTDBGCFGPROP_FLAGS,
271	/** List of paths to search for symbol files and images.
272	* Env: _PATH */
273	RTDBGCFGPROP_PATH,
274	/** List of symbol file suffixes (semicolon separated).
275	* Env: _SUFFIXES */
276	RTDBGCFGPROP_SUFFIXES,
277	/** List of paths to search for source files.
278	* Env: _SRC_PATH */
279	RTDBGCFGPROP_SRC_PATH,
280	/** End of valid values. */
281	RTDBGCFGPROP_END,
282	/** The customary 32-bit type hack. */
283	RTDBGCFGPROP_32BIT_HACK = 0x7fffffff
284	} RTDBGCFGPROP;
285
286	/**
287	* Configuration property change operation.
288	*/
289	typedef enum RTDBGCFGOP
290	{
291	/** Customary invalid 0 value. */
292	RTDBGCFGOP_INVALID = 0,
293	/** Replace the current value with the given one. */
294	RTDBGCFGOP_SET,
295	/** Append the given value to the existing one. For integer values this is
296	* considered a bitwise OR operation. */
297	RTDBGCFGOP_APPEND,
298	/** Prepend the given value to the existing one. For integer values this is
299	* considered a bitwise OR operation. */
300	RTDBGCFGOP_PREPEND,
301	/** Removes the value from the existing one. For interger values the value is
302	* complemented and ANDed with the existing one, clearing all the specified
303	* flags/bits. */
304	RTDBGCFGOP_REMOVE,
305	/** End of valid values. */
306	RTDBGCFGOP_END,
307	/** Customary 32-bit type hack. */
308	RTDBGCFGOP_32BIT_HACK = 0x7fffffff
309	} RTDBGCFGOP;
310
311
312
313	/**
314	* Initializes a debugging configuration.
315	*
316	* @returns IPRT status code.
317	* @param phDbgCfg Where to return the configuration handle.
318	* @param pszEnvVarPrefix The environment variable prefix. If NULL, the
319	* environment is not consulted.
320	* @param fNativePaths Whether to pick up native paths from the
321	* environment.
322	*
323	* @sa RTDbgCfgChangeString, RTDbgCfgChangeUInt.
324	*/
325	RTDECL(int) RTDbgCfgCreate(PRTDBGCFG phDbgCfg, const char *pszEnvVarPrefix, bool fNativePaths);
326
327	/**
328	* Retains a new reference to a debugging config.
329	*
330	* @returns New reference count.
331	* UINT32_MAX is returned if the handle is invalid (asserted).
332	* @param hDbgCfg The config handle.
333	*/
334	RTDECL(uint32_t) RTDbgCfgRetain(RTDBGCFG hDbgCfg);
335
336	/**
337	* Releases a references to a debugging config.
338	*
339	* @returns New reference count, if 0 the config was freed. UINT32_MAX is
340	* returned if the handle is invalid (asserted).
341	* @param hDbgCfg The config handle.
342	*/
343	RTDECL(uint32_t) RTDbgCfgRelease(RTDBGCFG hDbgCfg);
344
345	/**
346	* Changes a property value by string.
347	*
348	* For string values the string is used more or less as given. For integer
349	* values and flags, it can contains both values (ORed together) or property
350	* specific mnemonics (ORed / ~ANDed).
351	*
352	* @returns IPRT status code.
353	* @retval VERR_DBG_CFG_INVALID_VALUE
354	* @param hDbgCfg The debugging configuration handle.
355	* @param enmProp The property to change.
356	* @param enmOp How to change the property.
357	* @param pszValue The property value to apply.
358	*/
359	RTDECL(int) RTDbgCfgChangeString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, const char *pszValue);
360
361	/**
362	* Changes a property value by unsigned integer (64-bit).
363	*
364	* This can only be applied to integer and flag properties.
365	*
366	* @returns IPRT status code.
367	* @retval VERR_DBG_CFG_NOT_UINT_PROP
368	* @param hDbgCfg The debugging configuration handle.
369	* @param enmProp The property to change.
370	* @param enmOp How to change the property.
371	* @param uValue The property value to apply.
372	*/
373	RTDECL(int) RTDbgCfgChangeUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, uint64_t uValue);
374
375	/**
376	* Query a property value as string.
377	*
378	* Integer and flags properties are returned as a list of mnemonics if possible,
379	* otherwise as simple hex values.
380	*
381	* @returns IPRT status code.
382	* @retval VERR_BUFFER_OVERFLOW if there isn't sufficient buffer space. Nothing
383	* is written.
384	* @param hDbgCfg The debugging configuration handle.
385	* @param enmProp The property to change.
386	* @param pszValue The output buffer.
387	* @param cbValue The size of the output buffer.
388	*/
389	RTDECL(int) RTDbgCfgQueryString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, char *pszValue, size_t cbValue);
390
391	/**
392	* Query a property value as unsigned integer (64-bit).
393	*
394	* Only integer and flags properties can be queried this way.
395	*
396	* @returns IPRT status code.
397	* @retval VERR_DBG_CFG_NOT_UINT_PROP
398	* @param hDbgCfg The debugging configuration handle.
399	* @param enmProp The property to change.
400	* @param puValue Where to return the value.
401	*/
402	RTDECL(int) RTDbgCfgQueryUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, uint64_t *puValue);
403
404	/**
405	* Log callback.
406	*
407	* @param hDbgCfg The debug config instance.
408	* @param iLevel The message level.
409	* @param pszMsg The message.
410	* @param pvUser User argument.
411	*/
412	typedef DECLCALLBACK(void) FNRTDBGCFGLOG(RTDBGCFG hDbgCfg, uint32_t iLevel, const char pszMsg, void pvUser);
413	/** Pointer to a log callback. */
414	typedef FNRTDBGCFGLOG *PFNRTDBGCFGLOG;
415
416	/**
417	* Sets the log callback for the configuration.
418	*
419	* This will fail if there is already a log callback present, unless pfnCallback
420	* is NULL.
421	*
422	* @returns IPRT status code.
423	* @param hDbgCfg The debugging configuration handle.
424	* @param pfnCallback The callback function. NULL to unset.
425	* @param pvUser The user argument.
426	*/
427	RTDECL(int) RTDbgCfgSetLogCallback(RTDBGCFG hDbgCfg, PFNRTDBGCFGLOG pfnCallback, void *pvUser);
428
429	/**
430	* Callback used by the RTDbgCfgOpen function to try out a file that was found.
431	*
432	* @returns On statuses other than VINF_CALLBACK_RETURN and
433	* VERR_CALLBACK_RETURN the search will continue till the end of the
434	* list. These status codes will not necessarily be propagated to the
435	* caller in any consistent manner.
436	* @retval VINF_CALLBACK_RETURN if successuflly opened the file and it's time
437	* to return
438	* @retval VERR_CALLBACK_RETURN if we shouldn't stop searching.
439	*
440	* @param hDbgCfg The debugging configuration handle.
441	* @param pszFilename The path to the file that should be tried out.
442	* @param pvUser1 First user parameter.
443	* @param pvUser2 Second user parameter.
444	*/
445	typedef DECLCALLBACK(int) FNDBGCFGOPEN(RTDBGCFG hDbgCfg, const char pszFilename, void pvUser1, void *pvUser2);
446	/** Pointer to a open-file callback used to the RTDbgCfgOpen functions. */
447	typedef FNDBGCFGOPEN *PFNDBGCFGOPEN;
448
449
450	RTDECL(int) RTDbgCfgOpenPeImage(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
451	PFNDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
452	RTDECL(int) RTDbgCfgOpenPdb70(RTDBGCFG hDbgCfg, const char *pszFilename, PCRTUUID pUuid, uint32_t uAge,
453	PFNDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
454	RTDECL(int) RTDbgCfgOpenPdb20(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp, uint32_t uAge,
455	PFNDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
456	RTDECL(int) RTDbgCfgOpenDbg(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t cbImage, uint32_t uTimestamp,
457	PFNDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
458	RTDECL(int) RTDbgCfgOpenDwo(RTDBGCFG hDbgCfg, const char *pszFilename, uint32_t uCrc32,
459	PFNDBGCFGOPEN pfnCallback, void pvUser1, void pvUser2);
460
461
462	/** @} */
463
464
465	/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
466	* @{
467	*/
468
469	/**
470	* Creates an empty address space.
471	*
472	* @returns IPRT status code.
473	*
474	* @param phDbgAs Where to store the address space handle on success.
475	* @param FirstAddr The first address in the address space.
476	* @param LastAddr The last address in the address space.
477	* @param pszName The name of the address space.
478	*/
479	RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
480
481	/**
482	* Variant of RTDbgAsCreate that takes a name format string.
483	*
484	* @returns IPRT status code.
485	*
486	* @param phDbgAs Where to store the address space handle on success.
487	* @param FirstAddr The first address in the address space.
488	* @param LastAddr The last address in the address space.
489	* @param pszNameFmt The name format of the address space.
490	* @param va Format arguments.
491	*/
492	RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va);
493
494	/**
495	* Variant of RTDbgAsCreate that takes a name format string.
496	*
497	* @returns IPRT status code.
498	*
499	* @param phDbgAs Where to store the address space handle on success.
500	* @param FirstAddr The first address in the address space.
501	* @param LastAddr The last address in the address space.
502	* @param pszNameFmt The name format of the address space.
503	* @param ... Format arguments.
504	*/
505	RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...);
506
507	/**
508	* Retains a reference to the address space.
509	*
510	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
511	*
512	* @param hDbgAs The address space handle.
513	*
514	* @remarks Will not take any locks.
515	*/
516	RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
517
518	/**
519	* Release a reference to the address space.
520	*
521	* When the reference count reaches zero, the address space is destroyed.
522	* That means unlinking all the modules it currently contains, potentially
523	* causing some or all of them to be destroyed as they are managed by
524	* reference counting.
525	*
526	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
527	*
528	* @param hDbgAs The address space handle. The NIL handle is quietly
529	* ignored and 0 is returned.
530	*
531	* @remarks Will not take any locks.
532	*/
533	RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
534
535	/**
536	* Locks the address space for exclusive access.
537	*
538	* @returns IRPT status code
539	* @param hDbgAs The address space handle.
540	*/
541	RTDECL(int) RTDbgAsLockExcl(RTDBGAS hDbgAs);
542
543	/**
544	* Counters the actions of one RTDbgAsUnlockExcl call.
545	*
546	* @returns IRPT status code
547	* @param hDbgAs The address space handle.
548	*/
549	RTDECL(int) RTDbgAsUnlockExcl(RTDBGAS hDbgAs);
550
551	/**
552	* Gets the name of an address space.
553	*
554	* @returns read only address space name.
555	* NULL if hDbgAs is invalid.
556	*
557	* @param hDbgAs The address space handle.
558	*
559	* @remarks Will not take any locks.
560	*/
561	RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
562
563	/**
564	* Gets the first address in an address space.
565	*
566	* @returns The address.
567	* 0 if hDbgAs is invalid.
568	*
569	* @param hDbgAs The address space handle.
570	*
571	* @remarks Will not take any locks.
572	*/
573	RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
574
575	/**
576	* Gets the last address in an address space.
577	*
578	* @returns The address.
579	* 0 if hDbgAs is invalid.
580	*
581	* @param hDbgAs The address space handle.
582	*
583	* @remarks Will not take any locks.
584	*/
585	RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
586
587	/**
588	* Gets the number of modules in the address space.
589	*
590	* This can be used together with RTDbgAsModuleByIndex
591	* to enumerate the modules.
592	*
593	* @returns The number of modules.
594	*
595	* @param hDbgAs The address space handle.
596	*
597	* @remarks Will not take any locks.
598	*/
599	RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
600
601	/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
602	* @{ */
603	/** Replace all conflicting module.
604	* (The conflicting modules will be removed the address space and their
605	* references released.) */
606	#define RTDBGASLINK_FLAGS_REPLACE RT_BIT_32(0)
607	/** Mask containing the valid flags. */
608	#define RTDBGASLINK_FLAGS_VALID_MASK UINT32_C(0x00000001)
609	/** @} */
610
611	/**
612	* Links a module into the address space at the give address.
613	*
614	* The size of the mapping is determined using RTDbgModImageSize().
615	*
616	* @returns IPRT status code.
617	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
618	* outside the address space.
619	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
620	*
621	* @param hDbgAs The address space handle.
622	* @param hDbgMod The module handle of the module to be linked in.
623	* @param ImageAddr The address to link the module at.
624	* @param fFlags See RTDBGASLINK_FLAGS_*.
625	*/
626	RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
627
628	/**
629	* Links a segment into the address space at the give address.
630	*
631	* The size of the mapping is determined using RTDbgModSegmentSize().
632	*
633	* @returns IPRT status code.
634	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
635	* outside the address space.
636	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
637	*
638	* @param hDbgAs The address space handle.
639	* @param hDbgMod The module handle.
640	* @param iSeg The segment number (0-based) of the segment to be
641	* linked in.
642	* @param SegAddr The address to link the segment at.
643	* @param fFlags See RTDBGASLINK_FLAGS_*.
644	*/
645	RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
646
647	/**
648	* Unlinks all the mappings of a module from the address space.
649	*
650	* @returns IPRT status code.
651	* @retval VERR_NOT_FOUND if the module wasn't found.
652	*
653	* @param hDbgAs The address space handle.
654	* @param hDbgMod The module handle of the module to be unlinked.
655	*/
656	RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
657
658	/**
659	* Unlinks the mapping at the specified address.
660	*
661	* @returns IPRT status code.
662	* @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
663	*
664	* @param hDbgAs The address space handle.
665	* @param Addr The address within the mapping to be unlinked.
666	*/
667	RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
668
669	/**
670	* Get a the handle of a module in the address space by is index.
671	*
672	* @returns A retained handle to the specified module. The caller must release
673	* the returned reference.
674	* NIL_RTDBGMOD if invalid index or handle.
675	*
676	* @param hDbgAs The address space handle.
677	* @param iModule The index of the module to get.
678	*
679	* @remarks The module indexes may change after calls to RTDbgAsModuleLink,
680	* RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
681	* RTDbgAsModuleUnlinkByAddr.
682	*/
683	RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
684
685	/**
686	* Queries mapping module information by handle.
687	*
688	* @returns IPRT status code.
689	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
690	*
691	* @param hDbgAs The address space handle.
692	* @param Addr Address within the mapping of the module or segment.
693	* @param phMod Where to the return the retained module handle.
694	* Optional.
695	* @param pAddr Where to return the base address of the mapping.
696	* Optional.
697	* @param piSeg Where to return the segment index. This is set to
698	* NIL if the entire module is mapped as a single
699	* mapping. Optional.
700	*/
701	RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
702
703	/**
704	* Queries mapping module information by name.
705	*
706	* @returns IPRT status code.
707	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
708	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
709	*
710	* @param hDbgAs The address space handle.
711	* @param pszName The module name.
712	* @param iName There can be more than one module by the same name
713	* in an address space. This argument indicates which
714	* is meant. (0 based)
715	* @param phMod Where to the return the retained module handle.
716	*/
717	RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
718
719	/**
720	* Information about a mapping.
721	*
722	* This is used by RTDbgAsModuleGetMapByIndex.
723	*/
724	typedef struct RTDBGASMAPINFO
725	{
726	/** The mapping address. */
727	RTUINTPTR Address;
728	/** The segment mapped there.
729	* This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */
730	RTDBGSEGIDX iSeg;
731	} RTDBGASMAPINFO;
732	/** Pointer to info about an address space mapping. */
733	typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
734	/** Pointer to const info about an address space mapping. */
735	typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO;
736
737	/**
738	* Queries mapping information for a module given by index.
739	*
740	* @returns IRPT status code.
741	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
742	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
743	* @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned
744	* information is incomplete.
745	*
746	* @param hDbgAs The address space handle.
747	* @param iModule The index of the module to get.
748	* @param paMappings Where to return the mapping information. The buffer
749	* size is given by *pcMappings.
750	* @param pcMappings IN: Size of the paMappings array. OUT: The number of
751	* entries returned.
752	* @param fFlags Flags for reserved for future use. MBZ.
753	*
754	* @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
755	* iModule parameter.
756	*/
757	RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags);
758
759	/**
760	* Adds a symbol to a module in the address space.
761	*
762	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
763	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
764	* @retval VERR_NOT_FOUND if no module was found at the specified address.
765	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
766	* custom symbols.
767	*
768	* @param hDbgAs The address space handle.
769	* @param pszSymbol The symbol name.
770	* @param Addr The address of the symbol.
771	* @param cb The size of the symbol.
772	* @param fFlags Symbol flags.
773	* @param piOrdinal Where to return the symbol ordinal on success. If
774	* the interpreter doesn't do ordinals, this will be set to
775	* UINT32_MAX. Optional
776	*/
777	RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t piOrdinal);
778
779	/**
780	* Query a symbol by address.
781	*
782	* @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
783	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
784	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
785	* @retval VERR_INVALID_PARAMETER if incorrect flags.
786	*
787	* @param hDbgAs The address space handle.
788	* @param Addr The address which closest symbol is requested.
789	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
790	* @param poffDisp Where to return the distance between the symbol
791	* and address. Optional.
792	* @param pSymbol Where to return the symbol info.
793	* @param phMod Where to return the module handle. Optional.
794	*/
795	RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
796	PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
797
798	/**
799	* Query a symbol by address.
800	*
801	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
802	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
803	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
804	* @retval VERR_INVALID_PARAMETER if incorrect flags.
805	*
806	* @param hDbgAs The address space handle.
807	* @param Addr The address which closest symbol is requested.
808	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
809	* @param poffDisp Where to return the distance between the symbol
810	* and address. Optional.
811	* @param ppSymInfo Where to return the pointer to the allocated symbol
812	* info. Always set. Free with RTDbgSymbolFree.
813	* @param phMod Where to return the module handle. Optional.
814	*/
815	RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
816	PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod);
817
818	/**
819	* Query a symbol by name.
820	*
821	* @returns IPRT status code.
822	* @retval VERR_SYMBOL_NOT_FOUND if not found.
823	*
824	* @param hDbgAs The address space handle.
825	* @param pszSymbol The symbol name. It is possible to limit the scope
826	* of the search by prefixing the symbol with a module
827	* name pattern followed by a bang (!) character.
828	* RTStrSimplePatternNMatch is used for the matching.
829	* @param pSymbol Where to return the symbol info.
830	* @param phMod Where to return the module handle. Optional.
831	*/
832	RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
833
834	/**
835	* Query a symbol by name, allocating the returned symbol structure.
836	*
837	* @returns IPRT status code.
838	* @retval VERR_SYMBOL_NOT_FOUND if not found.
839	*
840	* @param hDbgAs The address space handle.
841	* @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.
842	* @param ppSymbol Where to return the pointer to the allocated
843	* symbol info. Always set. Free with RTDbgSymbolFree.
844	* @param phMod Where to return the module handle. Optional.
845	*/
846	RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char pszSymbol, PRTDBGSYMBOL ppSymbol, PRTDBGMOD phMod);
847
848	/**
849	* Query a line number by address.
850	*
851	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
852	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
853	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
854	*
855	* @param hDbgAs The address space handle.
856	* @param Addr The address which closest symbol is requested.
857	* @param poffDisp Where to return the distance between the line
858	* number and address.
859	* @param pLine Where to return the line number information.
860	*/
861	RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
862
863	/**
864	* Adds a line number to a module in the address space.
865	*
866	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
867	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
868	* @retval VERR_NOT_FOUND if no module was found at the specified address.
869	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
870	* custom symbols.
871	*
872	* @param hDbgAs The address space handle.
873	* @param pszFile The file name.
874	* @param uLineNo The line number.
875	* @param Addr The address of the symbol.
876	* @param piOrdinal Where to return the line number ordinal on success.
877	* If the interpreter doesn't do ordinals, this will be
878	* set to UINT32_MAX. Optional.
879	*/
880	RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t piOrdinal);
881
882
883	/**
884	* Query a line number by address.
885	*
886	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
887	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
888	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
889	*
890	* @param hDbgAs The address space handle.
891	* @param Addr The address which closest symbol is requested.
892	* @param poffDisp Where to return the distance between the line
893	* number and address.
894	* @param pLine Where to return the line number information.
895	*/
896	RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
897
898	/**
899	* Query a line number by address.
900	*
901	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
902	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
903	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
904	*
905	* @param hDbgAs The address space handle.
906	* @param Addr The address which closest symbol is requested.
907	* @param poffDisp Where to return the distance between the line
908	* number and address.
909	* @param ppLine Where to return the pointer to the allocated line
910	* number info. Always set. Free with RTDbgLineFree.
911	*/
912	RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
913
914	/** @todo Missing some bits here. */
915
916	/** @} */
917
918
919	/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
920	* @{
921	*/
922
923	/**
924	* Creates a module based on the default debug info container.
925	*
926	* This can be used to manually load a module and its symbol. The primary user
927	* group is the debug info interpreters, which use this API to create an
928	* efficient debug info container behind the scenes and forward all queries to
929	* it once the info has been loaded.
930	*
931	* @returns IPRT status code.
932	*
933	* @param phDbgMod Where to return the module handle.
934	* @param pszName The name of the module (mandatory).
935	* @param cbSeg The size of initial segment. If zero, segments will
936	* have to be added manually using RTDbgModSegmentAdd.
937	* @param fFlags Flags reserved for future extensions, MBZ for now.
938	*/
939	RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
940
941	RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName,
942	RTDBGCFG hDbgCfg);
943	RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR uSubtrahend,
944	RTDBGCFG hDbgCfg);
945	RTDECL(int) RTDbgModCreateFromPeImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTLDRMOD hLdrMod,
946	uint32_t cbImage, uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
947	RTDECL(int) RTDbgModCreateFromDbg(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
948	uint32_t uTimeDateStamp, RTDBGCFG hDbgCfg);
949	RTDECL(int) RTDbgModCreateFromPdb(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
950	PCRTUUID pUuid, uint32_t Age, RTDBGCFG hDbgCfg);
951	RTDECL(int) RTDbgModCreateFromDwo(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
952	uint32_t uCrc32, RTDBGCFG hDbgCfg);
953
954
955	/**
956	* Retains another reference to the module.
957	*
958	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
959	*
960	* @param hDbgMod The module handle.
961	*
962	* @remarks Will not take any locks.
963	*/
964	RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
965
966	/**
967	* Release a reference to the module.
968	*
969	* When the reference count reaches zero, the module is destroyed.
970	*
971	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
972	*
973	* @param hDbgMod The module handle. The NIL handle is quietly ignored
974	* and 0 is returned.
975	*
976	* @remarks Will not take any locks.
977	*/
978	RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
979
980	/**
981	* Removes all content from the debug module (container), optionally only
982	* leaving segments and image size intact.
983	*
984	* This is only possible on container modules, i.e. created by RTDbgModCreate().
985	*
986	* @returns IPRT status code.
987	* @param hDbgMod The module handle.
988	* @param fLeaveSegments Whether to leave segments (and image size) as is.
989	*/
990	RTDECL(int) RTDbgModRemoveAll(RTDBGMOD hDbgMod, bool fLeaveSegments);
991
992	/**
993	* Gets the module name.
994	*
995	* @returns Pointer to a read only string containing the name.
996	*
997	* @param hDbgMod The module handle.
998	*/
999	RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
1000
1001	/**
1002	* Gets the name of the debug info file we're using.
1003	*
1004	* @returns Pointer to a read only string containing the filename, NULL if we
1005	* don't use one.
1006	*
1007	* @param hDbgMod The module handle.
1008	*/
1009	RTDECL(const char *) RTDbgModDebugFile(RTDBGMOD hDbgMod);
1010
1011	/**
1012	* Gets the image filename (as specified by the user).
1013	*
1014	* @returns Pointer to a read only string containing the filename.
1015	*
1016	* @param hDbgMod The module handle.
1017	*/
1018	RTDECL(const char *) RTDbgModImageFile(RTDBGMOD hDbgMod);
1019
1020	/**
1021	* Gets the image filename actually used if it differs from RTDbgModImageFile.
1022	*
1023	* @returns Pointer to a read only string containing the filename, NULL if same
1024	* as RTDBgModImageFile.
1025	*
1026	* @param hDbgMod The module handle.
1027	*/
1028	RTDECL(const char *) RTDbgModImageFileUsed(RTDBGMOD hDbgMod);
1029
1030	/**
1031	* Checks if the loading of the debug info has been postponed.
1032	*
1033	* @returns true if postponed, false if not or invalid handle.
1034	* @param hDbgMod The module handle.
1035	*/
1036	RTDECL(bool) RTDbgModIsDeferred(RTDBGMOD hDbgMod);
1037
1038	/**
1039	* Checks if the debug info is exports only.
1040	*
1041	* @returns true if exports only, false if not or invalid handle.
1042	* @param hDbgMod The module handle.
1043	*/
1044	RTDECL(bool) RTDbgModIsExports(RTDBGMOD hDbgMod);
1045
1046	/**
1047	* Converts an image relative address to a segment:offset address.
1048	*
1049	* @returns Segment index on success.
1050	* NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
1051	* invalid.
1052	*
1053	* @param hDbgMod The module handle.
1054	* @param uRva The image relative address to convert.
1055	* @param poffSeg Where to return the segment offset. Optional.
1056	*/
1057	RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
1058
1059	/**
1060	* Image size when mapped if segments are mapped adjacently.
1061	*
1062	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
1063	* NE and such it's a bit odder and the answer may not make much sense for them.
1064	*
1065	* @returns Image mapped size.
1066	* RTUINTPTR_MAX is returned if the handle is invalid.
1067	*
1068	* @param hDbgMod The module handle.
1069	*/
1070	RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
1071
1072	/**
1073	* Gets the module tag value if any.
1074	*
1075	* @returns The tag. 0 if hDbgMod is invalid.
1076	*
1077	* @param hDbgMod The module handle.
1078	*/
1079	RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
1080
1081	/**
1082	* Tags or untags the module.
1083	*
1084	* @returns IPRT status code.
1085	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1086	*
1087	* @param hDbgMod The module handle.
1088	* @param uTag The tag value. The convention is that 0 is no tag
1089	* and any other value means it's tagged. It's adviced
1090	* to use some kind of unique number like an address
1091	* (global or string cache for instance) to avoid
1092	* collisions with other users
1093	*/
1094	RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
1095
1096
1097	/**
1098	* Adds a segment to the module. Optional feature.
1099	*
1100	* This method is intended used for manually constructing debug info for a
1101	* module. The main usage is from other debug info interpreters that want to
1102	* avoid writing a debug info database and instead uses the standard container
1103	* behind the scenes.
1104	*
1105	* @returns IPRT status code.
1106	* @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
1107	* interpreter. This is a common return code.
1108	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1109	* @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
1110	* @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
1111	* @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
1112	* @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
1113	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
1114	*
1115	* @param hDbgMod The module handle.
1116	* @param uRva The image relative address of the segment.
1117	* @param cb The size of the segment.
1118	* @param pszName The segment name. Does not normally need to be
1119	* unique, although this is somewhat up to the
1120	* debug interpreter to decide.
1121	* @param fFlags Segment flags. Reserved for future used, MBZ.
1122	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
1123	* The assigned segment index on successful return.
1124	* Optional.
1125	*/
1126	RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
1127	uint32_t fFlags, PRTDBGSEGIDX piSeg);
1128
1129	/**
1130	* Gets the number of segments in the module.
1131	*
1132	* This is can be used to determine the range which can be passed to
1133	* RTDbgModSegmentByIndex and derivates.
1134	*
1135	* @returns The segment relative address.
1136	* NIL_RTDBGSEGIDX if the handle is invalid.
1137	*
1138	* @param hDbgMod The module handle.
1139	*/
1140	RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
1141
1142	/**
1143	* Query information about a segment.
1144	*
1145	* This can be used together with RTDbgModSegmentCount to enumerate segments.
1146	* The index starts a 0 and stops one below RTDbgModSegmentCount.
1147	*
1148	* @returns IPRT status code.
1149	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
1150	* @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
1151	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1152	*
1153	* @param hDbgMod The module handle.
1154	* @param iSeg The segment index. No special segments.
1155	* @param pSegInfo Where to return the segment info. The
1156	* RTDBGSEGMENT::Address member will be set to
1157	* RTUINTPTR_MAX or the load address used at link time.
1158	*/
1159	RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
1160
1161	/**
1162	* Gets the size of a segment.
1163	*
1164	* This is a just a wrapper around RTDbgModSegmentByIndex.
1165	*
1166	* @returns The segment size.
1167	* RTUINTPTR_MAX is returned if either the handle and segment index are
1168	* invalid.
1169	*
1170	* @param hDbgMod The module handle.
1171	* @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
1172	* If RTDBGSEGIDX_RVA is used, the functions returns
1173	* the same value as RTDbgModImageSize.
1174	*/
1175	RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1176
1177	/**
1178	* Gets the image relative address of a segment.
1179	*
1180	* This is a just a wrapper around RTDbgModSegmentByIndex.
1181	*
1182	* @returns The segment relative address.
1183	* RTUINTPTR_MAX is returned if either the handle and segment index are
1184	* invalid.
1185	*
1186	* @param hDbgMod The module handle.
1187	* @param iSeg The segment index. No special segment indexes
1188	* allowed (asserted).
1189	*/
1190	RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1191
1192
1193	/**
1194	* Adds a line number to the module.
1195	*
1196	* @returns IPRT status code.
1197	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1198	* custom symbols. This is a common place occurrence.
1199	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1200	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1201	* short.
1202	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1203	* it's not inside any of the segments defined by the module.
1204	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1205	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1206	* end of the segment.
1207	* @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
1208	* @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
1209	*
1210	* @param hDbgMod The module handle.
1211	* @param pszSymbol The symbol name.
1212	* @param iSeg The segment index.
1213	* @param off The segment offset.
1214	* @param cb The size of the symbol. Can be zero, although this
1215	* may depend somewhat on the debug interpreter.
1216	* @param fFlags Symbol flags. Reserved for the future, MBZ.
1217	* @param piOrdinal Where to return the symbol ordinal on success. If
1218	* the interpreter doesn't do ordinals, this will be set to
1219	* UINT32_MAX. Optional.
1220	*/
1221	RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
1222	RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
1223
1224	/**
1225	* Gets the symbol count.
1226	*
1227	* This can be used together wtih RTDbgModSymbolByOrdinal or
1228	* RTDbgModSymbolByOrdinalA to enumerate all the symbols.
1229	*
1230	* @returns The number of symbols in the module.
1231	* UINT32_MAX is returned if the module handle is invalid or some other
1232	* error occurs.
1233	*
1234	* @param hDbgMod The module handle.
1235	*/
1236	RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
1237
1238	/**
1239	* Queries symbol information by ordinal number.
1240	*
1241	* @returns IPRT status code.
1242	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1243	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1244	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1245	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1246	*
1247	* @param hDbgMod The module handle.
1248	* @param iOrdinal The symbol ordinal number. 0-based. The highest
1249	* number is RTDbgModSymbolCount() - 1.
1250	* @param pSymInfo Where to store the symbol information.
1251	*/
1252	RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
1253
1254	/**
1255	* Queries symbol information by ordinal number.
1256	*
1257	* @returns IPRT status code.
1258	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1259	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1260	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1261	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1262	*
1263	* @param hDbgMod The module handle.
1264	* @param iOrdinal The symbol ordinal number. 0-based. The highest
1265	* number is RTDbgModSymbolCount() - 1.
1266	* @param ppSymInfo Where to store the pointer to the returned
1267	* symbol information. Always set. Free with
1268	* RTDbgSymbolFree.
1269	*/
1270	RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
1271
1272	/**
1273	* Queries symbol information by address.
1274	*
1275	* The returned symbol is what the debug info interpreter considers the symbol
1276	* most applicable to the specified address. This usually means a symbol with an
1277	* address equal or lower than the requested.
1278	*
1279	* @returns IPRT status code.
1280	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1281	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1282	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1283	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1284	* it's not inside any of the segments defined by the module.
1285	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1286	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1287	* end of the segment.
1288	* @retval VERR_INVALID_PARAMETER if incorrect flags.
1289	*
1290	* @param hDbgMod The module handle.
1291	* @param iSeg The segment number.
1292	* @param off The offset into the segment.
1293	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1294	* @param poffDisp Where to store the distance between the
1295	* specified address and the returned symbol.
1296	* Optional.
1297	* @param pSymInfo Where to store the symbol information.
1298	*/
1299	RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1300	PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
1301
1302	/**
1303	* Queries symbol information by address.
1304	*
1305	* The returned symbol is what the debug info interpreter considers the symbol
1306	* most applicable to the specified address. This usually means a symbol with an
1307	* address equal or lower than the requested.
1308	*
1309	* @returns IPRT status code.
1310	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1311	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1312	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1313	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1314	* it's not inside any of the segments defined by the module.
1315	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1316	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1317	* end of the segment.
1318	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1319	* @retval VERR_INVALID_PARAMETER if incorrect flags.
1320	*
1321	* @param hDbgMod The module handle.
1322	* @param iSeg The segment index.
1323	* @param off The offset into the segment.
1324	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1325	* @param poffDisp Where to store the distance between the
1326	* specified address and the returned symbol. Optional.
1327	* @param ppSymInfo Where to store the pointer to the returned
1328	* symbol information. Always set. Free with
1329	* RTDbgSymbolFree.
1330	*/
1331	RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1332	PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
1333
1334	/**
1335	* Queries symbol information by symbol name.
1336	*
1337	* @returns IPRT status code.
1338	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1339	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1340	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1341	* short.
1342	*
1343	* @param hDbgMod The module handle.
1344	* @param pszSymbol The symbol name.
1345	* @param pSymInfo Where to store the symbol information.
1346	*/
1347	RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
1348
1349	/**
1350	* Queries symbol information by symbol name.
1351	*
1352	* @returns IPRT status code.
1353	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1354	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1355	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1356	* short.
1357	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1358	*
1359	* @param hDbgMod The module handle.
1360	* @param pszSymbol The symbol name.
1361	* @param ppSymInfo Where to store the pointer to the returned
1362	* symbol information. Always set. Free with
1363	* RTDbgSymbolFree.
1364	*/
1365	RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char pszSymbol, PRTDBGSYMBOL ppSymInfo);
1366
1367	/**
1368	* Adds a line number to the module.
1369	*
1370	* @returns IPRT status code.
1371	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1372	* custom symbols. This should be consider a normal response.
1373	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1374	* @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1375	* empty.
1376	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1377	* it's not inside any of the segments defined by the module.
1378	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1379	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1380	* end of the segment.
1381	* @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1382	*
1383	* @param hDbgMod The module handle.
1384	* @param pszFile The file name.
1385	* @param uLineNo The line number.
1386	* @param iSeg The segment index.
1387	* @param off The segment offset.
1388	* @param piOrdinal Where to return the line number ordinal on
1389	* success. If the interpreter doesn't do ordinals,
1390	* this will be set to UINT32_MAX. Optional.
1391	*/
1392	RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1393	RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1394
1395	/**
1396	* Gets the line number count.
1397	*
1398	* This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1399	* to enumerate all the line number information.
1400	*
1401	* @returns The number of line numbers in the module.
1402	* UINT32_MAX is returned if the module handle is invalid or some other
1403	* error occurs.
1404	*
1405	* @param hDbgMod The module handle.
1406	*/
1407	RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1408
1409	/**
1410	* Queries line number information by ordinal number.
1411	*
1412	* This can be used to enumerate the line numbers for the module. Use
1413	* RTDbgModLineCount() to figure the end of the ordinals.
1414	*
1415	* @returns IPRT status code.
1416	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1417	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1418	* ordinal.
1419	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1420
1421	* @param hDbgMod The module handle.
1422	* @param iOrdinal The line number ordinal number.
1423	* @param pLineInfo Where to store the information about the line
1424	* number.
1425	*/
1426	RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1427
1428	/**
1429	* Queries line number information by ordinal number.
1430	*
1431	* This can be used to enumerate the line numbers for the module. Use
1432	* RTDbgModLineCount() to figure the end of the ordinals.
1433	*
1434	* @returns IPRT status code.
1435	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1436	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1437	* ordinal.
1438	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1439	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1440	*
1441	* @param hDbgMod The module handle.
1442	* @param iOrdinal The line number ordinal number.
1443	* @param ppLineInfo Where to store the pointer to the returned line
1444	* number information. Always set. Free with
1445	* RTDbgLineFree.
1446	*/
1447	RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1448
1449	/**
1450	* Queries line number information by address.
1451	*
1452	* The returned line number is what the debug info interpreter considers the
1453	* one most applicable to the specified address. This usually means a line
1454	* number with an address equal or lower than the requested.
1455	*
1456	* @returns IPRT status code.
1457	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1458	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1459	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1460	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1461	* it's not inside any of the segments defined by the module.
1462	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1463	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1464	* end of the segment.
1465	*
1466	* @param hDbgMod The module handle.
1467	* @param iSeg The segment number.
1468	* @param off The offset into the segment.
1469	* @param poffDisp Where to store the distance between the
1470	* specified address and the returned symbol.
1471	* Optional.
1472	* @param pLineInfo Where to store the line number information.
1473	*/
1474	RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1475
1476	/**
1477	* Queries line number information by address.
1478	*
1479	* The returned line number is what the debug info interpreter considers the
1480	* one most applicable to the specified address. This usually means a line
1481	* number with an address equal or lower than the requested.
1482	*
1483	* @returns IPRT status code.
1484	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1485	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1486	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1487	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1488	* it's not inside any of the segments defined by the module.
1489	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1490	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1491	* end of the segment.
1492	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1493	*
1494	* @param hDbgMod The module handle.
1495	* @param iSeg The segment number.
1496	* @param off The offset into the segment.
1497	* @param poffDisp Where to store the distance between the
1498	* specified address and the returned symbol.
1499	* Optional.
1500	* @param ppLineInfo Where to store the pointer to the returned line
1501	* number information. Always set. Free with
1502	* RTDbgLineFree.
1503	*/
1504	RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1505	/** @} */
1506
1507	# endif /* IN_RING3 */
1508
1509
1510	/** @name Kernel Debug Info API
1511	*
1512	* This is a specialized API for obtaining symbols and structure information
1513	* about the running kernel. It is relatively OS specific. Its purpose and
1514	* operation is doesn't map all that well onto RTDbgMod, so a few dedicated
1515	* functions was created for it.
1516	*
1517	* @{ */
1518
1519	/** Handle to the kernel debug info. */
1520	typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO;
1521	/** Pointer to a kernel debug info handle. */
1522	typedef RTDBGKRNLINFO *PRTDBGKRNLINFO;
1523	/** Nil kernel debug info handle. */
1524	#define NIL_RTDBGKRNLINFO ((RTDBGKRNLINFO)0)
1525
1526	/**
1527	* Opens the kernel debug info.
1528	*
1529	* @returns IPRT status code. Can fail for any number of reasons.
1530	*
1531	* @param phKrnlInfo Where to return the kernel debug info handle on
1532	* success.
1533	* @param fFlags Flags reserved for future use. Must be zero.
1534	*/
1535	RTR0DECL(int) RTR0DbgKrnlInfoOpen(PRTDBGKRNLINFO phKrnlInfo, uint32_t fFlags);
1536
1537	/**
1538	* Retains a reference to the kernel debug info handle.
1539	*
1540	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
1541	* @param hKrnlInfo The kernel info handle.
1542	*/
1543	RTR0DECL(uint32_t) RTR0DbgKrnlInfoRetain(RTDBGKRNLINFO hKrnlInfo);
1544
1545
1546	/**
1547	* Releases a reference to the kernel debug info handle, destroying it when the
1548	* counter reaches zero.
1549	*
1550	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
1551	* @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is
1552	* quietly ignored.
1553	*/
1554	RTR0DECL(uint32_t) RTR0DbgKrnlInfoRelease(RTDBGKRNLINFO hKrnlInfo);
1555
1556	/**
1557	* Queries the offset (in bytes) of a member of a kernel structure.
1558	*
1559	* @returns IPRT status code.
1560	* @retval VINF_SUCCESS and offset at @a poffMember.
1561	* @retval VERR_NOT_FOUND if the structure or the member was not found.
1562	* @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1563	* @retval VERR_INVALID_POINTER if any of the pointers are bad.
1564	*
1565	* @param hKrnlInfo The kernel info handle.
1566	* @param pszStructure The structure name.
1567	* @param pszMember The member name.
1568	* @param poffMember Where to return the offset.
1569	*/
1570	RTR0DECL(int) RTR0DbgKrnlInfoQueryMember(RTDBGKRNLINFO hKrnlInfo, const char *pszStructure,
1571	const char pszMember, size_t poffMember);
1572
1573
1574	/**
1575	* Queries the value (usually the address) of a kernel symbol.
1576	*
1577	* This may go looking for the symbol in other modules, in which case it will
1578	* always check the kernel symbol table first.
1579	*
1580	* @returns IPRT status code.
1581	* @retval VINF_SUCCESS and value at @a ppvSymbol.
1582	* @retval VERR_SYMBOL_NOT_FOUND
1583	* @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1584	* @retval VERR_INVALID_POINTER if any of the pointers are bad.
1585	*
1586	* @param hKrnlInfo The kernel info handle.
1587	* @param pszModule Reserved for future extensions. Pass NULL.
1588	* @param pszSymbol The C name of the symbol.
1589	* @param ppvSymbol Where to return the symbol value, passing NULL is
1590	* OK. This may be modified even on failure, in
1591	* particular, it will be set to NULL when
1592	* VERR_SYMBOL_NOT_FOUND is returned.
1593	*
1594	* @sa RTLdrGetSymbol.
1595	*/
1596	RTR0DECL(int) RTR0DbgKrnlInfoQuerySymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1597	const char pszSymbol, void *ppvSymbol);
1598	/** @} */
1599
1600	/** @} */
1601
1602	RT_C_DECLS_END
1603
1604	#endif
1605

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

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

Download in other formats: