dbg.h@ 45985

Last change on this file since 45985 was 45985, checked in by vboxsync, 12 years ago
RTDbgCfg: Debugging configuration, like symbol search paths and such.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 57.2 KB

Line
1	/* $Id: dbg.h 45985 2013-05-11 13:14:22Z 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	*
321	* @sa RTDbgCfgChangeString, RTDbgCfgChangeUInt.
322	*/
323	RTDECL(int) RTDbgCfgCreate(PRTDBGCFG phDbgCfg, const char *pszEnvVarPrefix);
324
325	/**
326	* Retains a new reference to a debugging config.
327	*
328	* @returns New reference count.
329	* UINT32_MAX is returned if the handle is invalid (asserted).
330	* @param hDbgCfg The config handle.
331	*/
332	RTDECL(uint32_t) RTDbgCfgRetain(RTDBGCFG hDbgCfg);
333
334	/**
335	* Releases a references to a debugging config.
336	*
337	* @returns New reference count, if 0 the config was freed. UINT32_MAX is
338	* returned if the handle is invalid (asserted).
339	* @param hDbgCfg The config handle.
340	*/
341	RTDECL(uint32_t) RTDbgCfgRelease(RTDBGCFG hDbgCfg);
342
343	/**
344	* Changes a property value by string.
345	*
346	* For string values the string is used more or less as given. For integer
347	* values and flags, it can contains both values (ORed together) or property
348	* specific mnemonics (ORed / ~ANDed).
349	*
350	* @returns IPRT status code.
351	* @retval VERR_DBG_CFG_INVALID_VALUE
352	* @param hDbgCfg The debugging configuration handle.
353	* @param enmProp The property to change.
354	* @param enmOp How to change the property.
355	* @param pszValue The property value to apply.
356	*/
357	RTDECL(int) RTDbgCfgChangeString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, const char *pszValue);
358
359	/**
360	* Changes a property value by unsigned integer (64-bit).
361	*
362	* This can only be applied to integer and flag properties.
363	*
364	* @returns IPRT status code.
365	* @retval VERR_DBG_CFG_NOT_UINT_PROP
366	* @param hDbgCfg The debugging configuration handle.
367	* @param enmProp The property to change.
368	* @param enmOp How to change the property.
369	* @param uValue The property value to apply.
370	*/
371	RTDECL(int) RTDbgCfgChangeUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, RTDBGCFGOP enmOp, uint64_t uValue);
372
373	/**
374	* Query a property value as string.
375	*
376	* Integer and flags properties are returned as a list of mnemonics if possible,
377	* otherwise as simple hex values.
378	*
379	* @returns IPRT status code.
380	* @retval VERR_BUFFER_OVERFLOW if there isn't sufficient buffer space. Nothing
381	* is written.
382	* @param hDbgCfg The debugging configuration handle.
383	* @param enmProp The property to change.
384	* @param pszValue The output buffer.
385	* @param cbValue The size of the output buffer.
386	*/
387	RTDECL(int) RTDbgCfgQueryString(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, char *pszValue, size_t cbValue);
388
389	/**
390	* Query a property value as unsigned integer (64-bit).
391	*
392	* Only integer and flags properties can be queried this way.
393	*
394	* @returns IPRT status code.
395	* @retval VERR_DBG_CFG_NOT_UINT_PROP
396	* @param hDbgCfg The debugging configuration handle.
397	* @param enmProp The property to change.
398	* @param puValue Where to return the value.
399	*/
400	RTDECL(int) RTDbgCfgQueryUInt(RTDBGCFG hDbgCfg, RTDBGCFGPROP enmProp, uint64_t *puValue);
401
402	/** @} */
403
404
405	/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
406	* @{
407	*/
408
409	/**
410	* Creates an empty address space.
411	*
412	* @returns IPRT status code.
413	*
414	* @param phDbgAs Where to store the address space handle on success.
415	* @param FirstAddr The first address in the address space.
416	* @param LastAddr The last address in the address space.
417	* @param pszName The name of the address space.
418	*/
419	RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
420
421	/**
422	* Variant of RTDbgAsCreate that takes a name format string.
423	*
424	* @returns IPRT status code.
425	*
426	* @param phDbgAs Where to store the address space handle on success.
427	* @param FirstAddr The first address in the address space.
428	* @param LastAddr The last address in the address space.
429	* @param pszNameFmt The name format of the address space.
430	* @param va Format arguments.
431	*/
432	RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va);
433
434	/**
435	* Variant of RTDbgAsCreate that takes a name format string.
436	*
437	* @returns IPRT status code.
438	*
439	* @param phDbgAs Where to store the address space handle on success.
440	* @param FirstAddr The first address in the address space.
441	* @param LastAddr The last address in the address space.
442	* @param pszNameFmt The name format of the address space.
443	* @param ... Format arguments.
444	*/
445	RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...);
446
447	/**
448	* Retains a reference to the address space.
449	*
450	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
451	*
452	* @param hDbgAs The address space handle.
453	*
454	* @remarks Will not take any locks.
455	*/
456	RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
457
458	/**
459	* Release a reference to the address space.
460	*
461	* When the reference count reaches zero, the address space is destroyed.
462	* That means unlinking all the modules it currently contains, potentially
463	* causing some or all of them to be destroyed as they are managed by
464	* reference counting.
465	*
466	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
467	*
468	* @param hDbgAs The address space handle. The NIL handle is quietly
469	* ignored and 0 is returned.
470	*
471	* @remarks Will not take any locks.
472	*/
473	RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
474
475	/**
476	* Gets the name of an address space.
477	*
478	* @returns read only address space name.
479	* NULL if hDbgAs is invalid.
480	*
481	* @param hDbgAs The address space handle.
482	*
483	* @remarks Will not take any locks.
484	*/
485	RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
486
487	/**
488	* Gets the first address in an address space.
489	*
490	* @returns The address.
491	* 0 if hDbgAs is invalid.
492	*
493	* @param hDbgAs The address space handle.
494	*
495	* @remarks Will not take any locks.
496	*/
497	RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
498
499	/**
500	* Gets the last address in an address space.
501	*
502	* @returns The address.
503	* 0 if hDbgAs is invalid.
504	*
505	* @param hDbgAs The address space handle.
506	*
507	* @remarks Will not take any locks.
508	*/
509	RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
510
511	/**
512	* Gets the number of modules in the address space.
513	*
514	* This can be used together with RTDbgAsModuleByIndex
515	* to enumerate the modules.
516	*
517	* @returns The number of modules.
518	*
519	* @param hDbgAs The address space handle.
520	*
521	* @remarks Will not take any locks.
522	*/
523	RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
524
525	/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
526	* @{ */
527	/** Replace all conflicting module.
528	* (The conflicting modules will be removed the address space and their
529	* references released.) */
530	#define RTDBGASLINK_FLAGS_REPLACE RT_BIT_32(0)
531	/** Mask containing the valid flags. */
532	#define RTDBGASLINK_FLAGS_VALID_MASK UINT32_C(0x00000001)
533	/** @} */
534
535	/**
536	* Links a module into the address space at the give address.
537	*
538	* The size of the mapping is determined using RTDbgModImageSize().
539	*
540	* @returns IPRT status code.
541	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
542	* outside the address space.
543	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
544	*
545	* @param hDbgAs The address space handle.
546	* @param hDbgMod The module handle of the module to be linked in.
547	* @param ImageAddr The address to link the module at.
548	* @param fFlags See RTDBGASLINK_FLAGS_*.
549	*/
550	RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
551
552	/**
553	* Links a segment into the address space at the give address.
554	*
555	* The size of the mapping is determined using RTDbgModSegmentSize().
556	*
557	* @returns IPRT status code.
558	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
559	* outside the address space.
560	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
561	*
562	* @param hDbgAs The address space handle.
563	* @param hDbgMod The module handle.
564	* @param iSeg The segment number (0-based) of the segment to be
565	* linked in.
566	* @param SegAddr The address to link the segment at.
567	* @param fFlags See RTDBGASLINK_FLAGS_*.
568	*/
569	RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
570
571	/**
572	* Unlinks all the mappings of a module from the address space.
573	*
574	* @returns IPRT status code.
575	* @retval VERR_NOT_FOUND if the module wasn't found.
576	*
577	* @param hDbgAs The address space handle.
578	* @param hDbgMod The module handle of the module to be unlinked.
579	*/
580	RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
581
582	/**
583	* Unlinks the mapping at the specified address.
584	*
585	* @returns IPRT status code.
586	* @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
587	*
588	* @param hDbgAs The address space handle.
589	* @param Addr The address within the mapping to be unlinked.
590	*/
591	RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
592
593	/**
594	* Get a the handle of a module in the address space by is index.
595	*
596	* @returns A retained handle to the specified module. The caller must release
597	* the returned reference.
598	* NIL_RTDBGMOD if invalid index or handle.
599	*
600	* @param hDbgAs The address space handle.
601	* @param iModule The index of the module to get.
602	*
603	* @remarks The module indexes may change after calls to RTDbgAsModuleLink,
604	* RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
605	* RTDbgAsModuleUnlinkByAddr.
606	*/
607	RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
608
609	/**
610	* Queries mapping module information by handle.
611	*
612	* @returns IPRT status code.
613	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
614	*
615	* @param hDbgAs The address space handle.
616	* @param Addr Address within the mapping of the module or segment.
617	* @param phMod Where to the return the retained module handle.
618	* Optional.
619	* @param pAddr Where to return the base address of the mapping.
620	* Optional.
621	* @param piSeg Where to return the segment index. This is set to
622	* NIL if the entire module is mapped as a single
623	* mapping. Optional.
624	*/
625	RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
626
627	/**
628	* Queries mapping module information by name.
629	*
630	* @returns IPRT status code.
631	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
632	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
633	*
634	* @param hDbgAs The address space handle.
635	* @param pszName The module name.
636	* @param iName There can be more than one module by the same name
637	* in an address space. This argument indicates which
638	* is meant. (0 based)
639	* @param phMod Where to the return the retained module handle.
640	*/
641	RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
642
643	/**
644	* Information about a mapping.
645	*
646	* This is used by RTDbgAsModuleGetMapByIndex.
647	*/
648	typedef struct RTDBGASMAPINFO
649	{
650	/** The mapping address. */
651	RTUINTPTR Address;
652	/** The segment mapped there.
653	* This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */
654	RTDBGSEGIDX iSeg;
655	} RTDBGASMAPINFO;
656	/** Pointer to info about an address space mapping. */
657	typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
658	/** Pointer to const info about an address space mapping. */
659	typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO;
660
661	/**
662	* Queries mapping information for a module given by index.
663	*
664	* @returns IRPT status code.
665	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
666	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
667	* @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned
668	* information is incomplete.
669	*
670	* @param hDbgAs The address space handle.
671	* @param iModule The index of the module to get.
672	* @param paMappings Where to return the mapping information. The buffer
673	* size is given by *pcMappings.
674	* @param pcMappings IN: Size of the paMappings array. OUT: The number of
675	* entries returned.
676	* @param fFlags Flags for reserved for future use. MBZ.
677	*
678	* @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
679	* iModule parameter.
680	*/
681	RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags);
682
683	/**
684	* Adds a symbol to a module in the address space.
685	*
686	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
687	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
688	* @retval VERR_NOT_FOUND if no module was found at the specified address.
689	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
690	* custom symbols.
691	*
692	* @param hDbgAs The address space handle.
693	* @param pszSymbol The symbol name.
694	* @param Addr The address of the symbol.
695	* @param cb The size of the symbol.
696	* @param fFlags Symbol flags.
697	* @param piOrdinal Where to return the symbol ordinal on success. If
698	* the interpreter doesn't do ordinals, this will be set to
699	* UINT32_MAX. Optional
700	*/
701	RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t piOrdinal);
702
703	/**
704	* Query a symbol by address.
705	*
706	* @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
707	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
708	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
709	* @retval VERR_INVALID_PARAMETER if incorrect flags.
710	*
711	* @param hDbgAs The address space handle.
712	* @param Addr The address which closest symbol is requested.
713	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
714	* @param poffDisp Where to return the distance between the symbol
715	* and address. Optional.
716	* @param pSymbol Where to return the symbol info.
717	* @param phMod Where to return the module handle. Optional.
718	*/
719	RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
720	PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
721
722	/**
723	* Query a symbol by address.
724	*
725	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
726	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
727	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
728	* @retval VERR_INVALID_PARAMETER if incorrect flags.
729	*
730	* @param hDbgAs The address space handle.
731	* @param Addr The address which closest symbol is requested.
732	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
733	* @param poffDisp Where to return the distance between the symbol
734	* and address. Optional.
735	* @param ppSymInfo Where to return the pointer to the allocated symbol
736	* info. Always set. Free with RTDbgSymbolFree.
737	* @param phMod Where to return the module handle. Optional.
738	*/
739	RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, uint32_t fFlags,
740	PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod);
741
742	/**
743	* Query a symbol by name.
744	*
745	* @returns IPRT status code.
746	* @retval VERR_SYMBOL_NOT_FOUND if not found.
747	*
748	* @param hDbgAs The address space handle.
749	* @param pszSymbol The symbol name. It is possible to limit the scope
750	* of the search by prefixing the symbol with a module
751	* name pattern followed by a bang (!) character.
752	* RTStrSimplePatternNMatch is used for the matching.
753	* @param pSymbol Where to return the symbol info.
754	* @param phMod Where to return the module handle. Optional.
755	*/
756	RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
757
758	/**
759	* Query a symbol by name, allocating the returned symbol structure.
760	*
761	* @returns IPRT status code.
762	* @retval VERR_SYMBOL_NOT_FOUND if not found.
763	*
764	* @param hDbgAs The address space handle.
765	* @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.
766	* @param ppSymbol Where to return the pointer to the allocated
767	* symbol info. Always set. Free with RTDbgSymbolFree.
768	* @param phMod Where to return the module handle. Optional.
769	*/
770	RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char pszSymbol, PRTDBGSYMBOL ppSymbol, PRTDBGMOD phMod);
771
772	/**
773	* Query a line number by address.
774	*
775	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
776	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
777	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
778	*
779	* @param hDbgAs The address space handle.
780	* @param Addr The address which closest symbol is requested.
781	* @param poffDisp Where to return the distance between the line
782	* number and address.
783	* @param pLine Where to return the line number information.
784	*/
785	RTDECL(int) RTDbgAs(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
786
787	/**
788	* Adds a line number to a module in the address space.
789	*
790	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
791	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
792	* @retval VERR_NOT_FOUND if no module was found at the specified address.
793	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
794	* custom symbols.
795	*
796	* @param hDbgAs The address space handle.
797	* @param pszFile The file name.
798	* @param uLineNo The line number.
799	* @param Addr The address of the symbol.
800	* @param piOrdinal Where to return the line number ordinal on success.
801	* If the interpreter doesn't do ordinals, this will be
802	* set to UINT32_MAX. Optional.
803	*/
804	RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t piOrdinal);
805
806
807	/**
808	* Query a line number by address.
809	*
810	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
811	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
812	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
813	*
814	* @param hDbgAs The address space handle.
815	* @param Addr The address which closest symbol is requested.
816	* @param poffDisp Where to return the distance between the line
817	* number and address.
818	* @param pLine Where to return the line number information.
819	*/
820	RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
821
822	/**
823	* Query a line number by address.
824	*
825	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
826	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
827	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
828	*
829	* @param hDbgAs The address space handle.
830	* @param Addr The address which closest symbol is requested.
831	* @param poffDisp Where to return the distance between the line
832	* number and address.
833	* @param ppLine Where to return the pointer to the allocated line
834	* number info. Always set. Free with RTDbgLineFree.
835	*/
836	RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
837
838	/** @todo Missing some bits here. */
839
840	/** @} */
841
842
843	/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
844	* @{
845	*/
846
847	/**
848	* Creates a module based on the default debug info container.
849	*
850	* This can be used to manually load a module and its symbol. The primary user
851	* group is the debug info interpreters, which use this API to create an
852	* efficient debug info container behind the scenes and forward all queries to
853	* it once the info has been loaded.
854	*
855	* @returns IPRT status code.
856	*
857	* @param phDbgMod Where to return the module handle.
858	* @param pszName The name of the module (mandatory).
859	* @param cbSeg The size of initial segment. If zero, segments will
860	* have to be added manually using RTDbgModSegmentAdd.
861	* @param fFlags Flags reserved for future extensions, MBZ for now.
862	*/
863	RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
864
865	RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName,
866	RTDBGCFG hDbgCfg);
867	RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR uSubtrahend,
868	RTDBGCFG hDbgCfg);
869	RTDECL(int) RTDbgModCreateFromPeImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
870	uint32_t uTimeDateStamp, RTDBGCFG pDbgCfg);
871	RTDECL(int) RTDbgModCreateFromDbg(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
872	uint32_t uTimeDateStamp, RTDBGCFG pDbgCfg);
873	RTDECL(int) RTDbgModCreateFromPdb(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
874	PCRTUUID pUuid, uint32_t Age, RTDBGCFG pDbgCfg);
875	RTDECL(int) RTDbgModCreateFromDwo(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t cbImage,
876	uint32_t uCrc32, RTDBGCFG pDbgCfg);
877
878
879	/**
880	* Retains another reference to the module.
881	*
882	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
883	*
884	* @param hDbgMod The module handle.
885	*
886	* @remarks Will not take any locks.
887	*/
888	RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
889
890	/**
891	* Release a reference to the module.
892	*
893	* When the reference count reaches zero, the module is destroyed.
894	*
895	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
896	*
897	* @param hDbgMod The module handle. The NIL handle is quietly ignored
898	* and 0 is returned.
899	*
900	* @remarks Will not take any locks.
901	*/
902	RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
903
904	/**
905	* Gets the module name.
906	*
907	* @returns Pointer to a read only string containing the name.
908	*
909	* @param hDbgMod The module handle.
910	*/
911	RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
912
913	/**
914	* Converts an image relative address to a segment:offset address.
915	*
916	* @returns Segment index on success.
917	* NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
918	* invalid.
919	*
920	* @param hDbgMod The module handle.
921	* @param uRva The image relative address to convert.
922	* @param poffSeg Where to return the segment offset. Optional.
923	*/
924	RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
925
926	/**
927	* Image size when mapped if segments are mapped adjacently.
928	*
929	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
930	* NE and such it's a bit odder and the answer may not make much sense for them.
931	*
932	* @returns Image mapped size.
933	* RTUINTPTR_MAX is returned if the handle is invalid.
934	*
935	* @param hDbgMod The module handle.
936	*/
937	RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
938
939	/**
940	* Gets the module tag value if any.
941	*
942	* @returns The tag. 0 if hDbgMod is invalid.
943	*
944	* @param hDbgMod The module handle.
945	*/
946	RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
947
948	/**
949	* Tags or untags the module.
950	*
951	* @returns IPRT status code.
952	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
953	*
954	* @param hDbgMod The module handle.
955	* @param uTag The tag value. The convention is that 0 is no tag
956	* and any other value means it's tagged. It's adviced
957	* to use some kind of unique number like an address
958	* (global or string cache for instance) to avoid
959	* collisions with other users
960	*/
961	RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
962
963
964	/**
965	* Adds a segment to the module. Optional feature.
966	*
967	* This method is intended used for manually constructing debug info for a
968	* module. The main usage is from other debug info interpreters that want to
969	* avoid writing a debug info database and instead uses the standard container
970	* behind the scenes.
971	*
972	* @returns IPRT status code.
973	* @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
974	* interpreter. This is a common return code.
975	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
976	* @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
977	* @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
978	* @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
979	* @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
980	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
981	*
982	* @param hDbgMod The module handle.
983	* @param uRva The image relative address of the segment.
984	* @param cb The size of the segment.
985	* @param pszName The segment name. Does not normally need to be
986	* unique, although this is somewhat up to the
987	* debug interpreter to decide.
988	* @param fFlags Segment flags. Reserved for future used, MBZ.
989	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
990	* The assigned segment index on successful return.
991	* Optional.
992	*/
993	RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
994	uint32_t fFlags, PRTDBGSEGIDX piSeg);
995
996	/**
997	* Gets the number of segments in the module.
998	*
999	* This is can be used to determine the range which can be passed to
1000	* RTDbgModSegmentByIndex and derivates.
1001	*
1002	* @returns The segment relative address.
1003	* NIL_RTDBGSEGIDX if the handle is invalid.
1004	*
1005	* @param hDbgMod The module handle.
1006	*/
1007	RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
1008
1009	/**
1010	* Query information about a segment.
1011	*
1012	* This can be used together with RTDbgModSegmentCount to enumerate segments.
1013	* The index starts a 0 and stops one below RTDbgModSegmentCount.
1014	*
1015	* @returns IPRT status code.
1016	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
1017	* @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
1018	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1019	*
1020	* @param hDbgMod The module handle.
1021	* @param iSeg The segment index. No special segments.
1022	* @param pSegInfo Where to return the segment info. The
1023	* RTDBGSEGMENT::Address member will be set to
1024	* RTUINTPTR_MAX or the load address used at link time.
1025	*/
1026	RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
1027
1028	/**
1029	* Gets the size of a segment.
1030	*
1031	* This is a just a wrapper around RTDbgModSegmentByIndex.
1032	*
1033	* @returns The segment size.
1034	* RTUINTPTR_MAX is returned if either the handle and segment index are
1035	* invalid.
1036	*
1037	* @param hDbgMod The module handle.
1038	* @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
1039	* If RTDBGSEGIDX_RVA is used, the functions returns
1040	* the same value as RTDbgModImageSize.
1041	*/
1042	RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1043
1044	/**
1045	* Gets the image relative address of a segment.
1046	*
1047	* This is a just a wrapper around RTDbgModSegmentByIndex.
1048	*
1049	* @returns The segment relative address.
1050	* RTUINTPTR_MAX is returned if either the handle and segment index are
1051	* invalid.
1052	*
1053	* @param hDbgMod The module handle.
1054	* @param iSeg The segment index. No special segment indexes
1055	* allowed (asserted).
1056	*/
1057	RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
1058
1059
1060	/**
1061	* Adds a line number to the module.
1062	*
1063	* @returns IPRT status code.
1064	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1065	* custom symbols. This is a common place occurrence.
1066	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1067	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1068	* short.
1069	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1070	* it's not inside any of the segments defined by the module.
1071	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1072	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1073	* end of the segment.
1074	* @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
1075	* @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
1076	*
1077	* @param hDbgMod The module handle.
1078	* @param pszSymbol The symbol name.
1079	* @param iSeg The segment index.
1080	* @param off The segment offset.
1081	* @param cb The size of the symbol. Can be zero, although this
1082	* may depend somewhat on the debug interpreter.
1083	* @param fFlags Symbol flags. Reserved for the future, MBZ.
1084	* @param piOrdinal Where to return the symbol ordinal on success. If
1085	* the interpreter doesn't do ordinals, this will be set to
1086	* UINT32_MAX. Optional.
1087	*/
1088	RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
1089	RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
1090
1091	/**
1092	* Gets the symbol count.
1093	*
1094	* This can be used together wtih RTDbgModSymbolByOrdinal or
1095	* RTDbgModSymbolByOrdinalA to enumerate all the symbols.
1096	*
1097	* @returns The number of symbols in the module.
1098	* UINT32_MAX is returned if the module handle is invalid or some other
1099	* error occurs.
1100	*
1101	* @param hDbgMod The module handle.
1102	*/
1103	RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
1104
1105	/**
1106	* Queries symbol information by ordinal number.
1107	*
1108	* @returns IPRT status code.
1109	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1110	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1111	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1112	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1113	*
1114	* @param hDbgMod The module handle.
1115	* @param iOrdinal The symbol ordinal number. 0-based. The highest
1116	* number is RTDbgModSymbolCount() - 1.
1117	* @param pSymInfo Where to store the symbol information.
1118	*/
1119	RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
1120
1121	/**
1122	* Queries symbol information by ordinal number.
1123	*
1124	* @returns IPRT status code.
1125	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1126	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
1127	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
1128	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1129	*
1130	* @param hDbgMod The module handle.
1131	* @param iOrdinal The symbol ordinal number. 0-based. The highest
1132	* number is RTDbgModSymbolCount() - 1.
1133	* @param ppSymInfo Where to store the pointer to the returned
1134	* symbol information. Always set. Free with
1135	* RTDbgSymbolFree.
1136	*/
1137	RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
1138
1139	/**
1140	* Queries symbol information by address.
1141	*
1142	* The returned symbol is what the debug info interpreter considers the symbol
1143	* most applicable to the specified address. This usually means a symbol with an
1144	* address equal or lower than the requested.
1145	*
1146	* @returns IPRT status code.
1147	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1148	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1149	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1150	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1151	* it's not inside any of the segments defined by the module.
1152	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1153	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1154	* end of the segment.
1155	* @retval VERR_INVALID_PARAMETER if incorrect flags.
1156	*
1157	* @param hDbgMod The module handle.
1158	* @param iSeg The segment number.
1159	* @param off The offset into the segment.
1160	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1161	* @param poffDisp Where to store the distance between the
1162	* specified address and the returned symbol.
1163	* Optional.
1164	* @param pSymInfo Where to store the symbol information.
1165	*/
1166	RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1167	PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
1168
1169	/**
1170	* Queries symbol information by address.
1171	*
1172	* The returned symbol is what the debug info interpreter considers the symbol
1173	* most applicable to the specified address. This usually means a symbol with an
1174	* address equal or lower than the requested.
1175	*
1176	* @returns IPRT status code.
1177	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1178	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1179	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1180	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1181	* it's not inside any of the segments defined by the module.
1182	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1183	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1184	* end of the segment.
1185	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1186	* @retval VERR_INVALID_PARAMETER if incorrect flags.
1187	*
1188	* @param hDbgMod The module handle.
1189	* @param iSeg The segment index.
1190	* @param off The offset into the segment.
1191	* @param fFlags Symbol search flags, see RTDBGSYMADDR_FLAGS_XXX.
1192	* @param poffDisp Where to store the distance between the
1193	* specified address and the returned symbol. Optional.
1194	* @param ppSymInfo Where to store the pointer to the returned
1195	* symbol information. Always set. Free with
1196	* RTDbgSymbolFree.
1197	*/
1198	RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t fFlags,
1199	PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
1200
1201	/**
1202	* Queries symbol information by symbol name.
1203	*
1204	* @returns IPRT status code.
1205	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1206	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1207	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1208	* short.
1209	*
1210	* @param hDbgMod The module handle.
1211	* @param pszSymbol The symbol name.
1212	* @param pSymInfo Where to store the symbol information.
1213	*/
1214	RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
1215
1216	/**
1217	* Queries symbol information by symbol name.
1218	*
1219	* @returns IPRT status code.
1220	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
1221	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
1222	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1223	* short.
1224	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1225	*
1226	* @param hDbgMod The module handle.
1227	* @param pszSymbol The symbol name.
1228	* @param ppSymInfo Where to store the pointer to the returned
1229	* symbol information. Always set. Free with
1230	* RTDbgSymbolFree.
1231	*/
1232	RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char pszSymbol, PRTDBGSYMBOL ppSymInfo);
1233
1234	/**
1235	* Adds a line number to the module.
1236	*
1237	* @returns IPRT status code.
1238	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1239	* custom symbols. This should be consider a normal response.
1240	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1241	* @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1242	* empty.
1243	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1244	* it's not inside any of the segments defined by the module.
1245	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1246	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1247	* end of the segment.
1248	* @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1249	*
1250	* @param hDbgMod The module handle.
1251	* @param pszFile The file name.
1252	* @param uLineNo The line number.
1253	* @param iSeg The segment index.
1254	* @param off The segment offset.
1255	* @param piOrdinal Where to return the line number ordinal on
1256	* success. If the interpreter doesn't do ordinals,
1257	* this will be set to UINT32_MAX. Optional.
1258	*/
1259	RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1260	RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1261
1262	/**
1263	* Gets the line number count.
1264	*
1265	* This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1266	* to enumerate all the line number information.
1267	*
1268	* @returns The number of line numbers in the module.
1269	* UINT32_MAX is returned if the module handle is invalid or some other
1270	* error occurs.
1271	*
1272	* @param hDbgMod The module handle.
1273	*/
1274	RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1275
1276	/**
1277	* Queries line number information by ordinal number.
1278	*
1279	* This can be used to enumerate the line numbers for the module. Use
1280	* RTDbgModLineCount() to figure the end of the ordinals.
1281	*
1282	* @returns IPRT status code.
1283	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1284	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1285	* ordinal.
1286	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1287
1288	* @param hDbgMod The module handle.
1289	* @param iOrdinal The line number ordinal number.
1290	* @param pLineInfo Where to store the information about the line
1291	* number.
1292	*/
1293	RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1294
1295	/**
1296	* Queries line number information by ordinal number.
1297	*
1298	* This can be used to enumerate the line numbers for the module. Use
1299	* RTDbgModLineCount() to figure the end of the ordinals.
1300	*
1301	* @returns IPRT status code.
1302	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1303	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1304	* ordinal.
1305	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1306	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1307	*
1308	* @param hDbgMod The module handle.
1309	* @param iOrdinal The line number ordinal number.
1310	* @param ppLineInfo Where to store the pointer to the returned line
1311	* number information. Always set. Free with
1312	* RTDbgLineFree.
1313	*/
1314	RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1315
1316	/**
1317	* Queries line number information by address.
1318	*
1319	* The returned line number is what the debug info interpreter considers the
1320	* one most applicable to the specified address. This usually means a line
1321	* number with an address equal or lower than the requested.
1322	*
1323	* @returns IPRT status code.
1324	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1325	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1326	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1327	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1328	* it's not inside any of the segments defined by the module.
1329	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1330	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1331	* end of the segment.
1332	*
1333	* @param hDbgMod The module handle.
1334	* @param iSeg The segment number.
1335	* @param off The offset into the segment.
1336	* @param poffDisp Where to store the distance between the
1337	* specified address and the returned symbol.
1338	* Optional.
1339	* @param pLineInfo Where to store the line number information.
1340	*/
1341	RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1342
1343	/**
1344	* Queries line number information by address.
1345	*
1346	* The returned line number is what the debug info interpreter considers the
1347	* one most applicable to the specified address. This usually means a line
1348	* number with an address equal or lower than the requested.
1349	*
1350	* @returns IPRT status code.
1351	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1352	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1353	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1354	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1355	* it's not inside any of the segments defined by the module.
1356	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1357	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1358	* end of the segment.
1359	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1360	*
1361	* @param hDbgMod The module handle.
1362	* @param iSeg The segment number.
1363	* @param off The offset into the segment.
1364	* @param poffDisp Where to store the distance between the
1365	* specified address and the returned symbol.
1366	* Optional.
1367	* @param ppLineInfo Where to store the pointer to the returned line
1368	* number information. Always set. Free with
1369	* RTDbgLineFree.
1370	*/
1371	RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1372	/** @} */
1373
1374	# endif /* IN_RING3 */
1375
1376
1377	/** @name Kernel Debug Info API
1378	*
1379	* This is a specialized API for obtaining symbols and structure information
1380	* about the running kernel. It is relatively OS specific. Its purpose and
1381	* operation is doesn't map all that well onto RTDbgMod, so a few dedicated
1382	* functions was created for it.
1383	*
1384	* @{ */
1385
1386	/** Handle to the kernel debug info. */
1387	typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO;
1388	/** Pointer to a kernel debug info handle. */
1389	typedef RTDBGKRNLINFO *PRTDBGKRNLINFO;
1390	/** Nil kernel debug info handle. */
1391	#define NIL_RTDBGKRNLINFO ((RTDBGKRNLINFO)0)
1392
1393	/**
1394	* Opens the kernel debug info.
1395	*
1396	* @returns IPRT status code. Can fail for any number of reasons.
1397	*
1398	* @param phKrnlInfo Where to return the kernel debug info handle on
1399	* success.
1400	* @param fFlags Flags reserved for future use. Must be zero.
1401	*/
1402	RTR0DECL(int) RTR0DbgKrnlInfoOpen(PRTDBGKRNLINFO phKrnlInfo, uint32_t fFlags);
1403
1404	/**
1405	* Retains a reference to the kernel debug info handle.
1406	*
1407	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
1408	* @param hKrnlInfo The kernel info handle.
1409	*/
1410	RTR0DECL(uint32_t) RTR0DbgKrnlInfoRetain(RTDBGKRNLINFO hKrnlInfo);
1411
1412
1413	/**
1414	* Releases a reference to the kernel debug info handle, destroying it when the
1415	* counter reaches zero.
1416	*
1417	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
1418	* @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is
1419	* quietly ignored.
1420	*/
1421	RTR0DECL(uint32_t) RTR0DbgKrnlInfoRelease(RTDBGKRNLINFO hKrnlInfo);
1422
1423	/**
1424	* Queries the offset (in bytes) of a member of a kernel structure.
1425	*
1426	* @returns IPRT status code.
1427	* @retval VINF_SUCCESS and offset at @a poffMember.
1428	* @retval VERR_NOT_FOUND if the structure or the member was not found.
1429	* @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1430	* @retval VERR_INVALID_POINTER if any of the pointers are bad.
1431	*
1432	* @param hKrnlInfo The kernel info handle.
1433	* @param pszStructure The structure name.
1434	* @param pszMember The member name.
1435	* @param poffMember Where to return the offset.
1436	*/
1437	RTR0DECL(int) RTR0DbgKrnlInfoQueryMember(RTDBGKRNLINFO hKrnlInfo, const char *pszStructure,
1438	const char pszMember, size_t poffMember);
1439
1440
1441	/**
1442	* Queries the value (usually the address) of a kernel symbol.
1443	*
1444	* This may go looking for the symbol in other modules, in which case it will
1445	* always check the kernel symbol table first.
1446	*
1447	* @returns IPRT status code.
1448	* @retval VINF_SUCCESS and value at @a ppvSymbol.
1449	* @retval VERR_SYMBOL_NOT_FOUND
1450	* @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1451	* @retval VERR_INVALID_POINTER if any of the pointers are bad.
1452	*
1453	* @param hKrnlInfo The kernel info handle.
1454	* @param pszModule Reserved for future extensions. Pass NULL.
1455	* @param pszSymbol The C name of the symbol.
1456	* @param ppvSymbol Where to return the symbol value, passing NULL is
1457	* OK. This may be modified even on failure, in
1458	* particular, it will be set to NULL when
1459	* VERR_SYMBOL_NOT_FOUND is returned.
1460	*
1461	* @sa RTLdrGetSymbol.
1462	*/
1463	RTR0DECL(int) RTR0DbgKrnlInfoQuerySymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1464	const char pszSymbol, void *ppvSymbol);
1465	/** @} */
1466
1467	/** @} */
1468
1469	RT_C_DECLS_END
1470
1471	#endif
1472

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

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

Download in other formats: