dbg.h@ 69387

Last change on this file since 69387 was 69105, checked in by vboxsync, 7 years ago
include/iprt/: (C) year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 65.1 KB

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

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

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

Download in other formats: