dbg.h@ 40979

Last change on this file since 40979 was 40855, checked in by vboxsync, 13 years ago
RTR0DbgKrnlInfo: Release shall accept NIL handle. Made QuerySymbol accept ppvSymbol=NULL. Promoted the magic.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 48.6 KB

Line
1	/* $Id: dbg.h 40855 2012-04-10 15:10:41Z vboxsync $ */
2	/** @file
3	* IPRT - Debugging Routines.
4	*/
5
6	/*
7	* Copyright (C) 2008-2009 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	/** Max length (including '\\0') of a segment name. */
65	#define RTDBG_SEGMENT_NAME_LENGTH (128 - 8 - 8 - 8 - 4 - 4)
66
67	/**
68	* Debug module segment.
69	*/
70	typedef struct RTDBGSEGMENT
71	{
72	/** The load address.
73	* RTUINTPTR_MAX if not applicable. */
74	RTUINTPTR Address;
75	/** The image relative virtual address of the segment.
76	* RTUINTPTR_MAX if not applicable. */
77	RTUINTPTR uRva;
78	/** The segment size. */
79	RTUINTPTR cb;
80	/** The segment flags. (reserved) */
81	uint32_t fFlags;
82	/** The segment index. */
83	RTDBGSEGIDX iSeg;
84	/** Symbol name. */
85	char szName[RTDBG_SEGMENT_NAME_LENGTH];
86	} RTDBGSEGMENT;
87	/** Pointer to a debug module segment. */
88	typedef RTDBGSEGMENT *PRTDBGSEGMENT;
89	/** Pointer to a const debug module segment. */
90	typedef RTDBGSEGMENT const *PCRTDBGSEGMENT;
91
92
93
94	/** Max length (including '\\0') of a symbol name. */
95	#define RTDBG_SYMBOL_NAME_LENGTH (384 - 8 - 8 - 8 - 4 - 4 - 8)
96
97	/**
98	* Debug symbol.
99	*/
100	typedef struct RTDBGSYMBOL
101	{
102	/** Symbol value (address).
103	* This depends a bit who you ask. It will be the same as offSeg when you
104	* as RTDbgMod, but the mapping address if you ask RTDbgAs. */
105	RTUINTPTR Value;
106	/** Symbol size. */
107	RTUINTPTR cb;
108	/** Offset into the segment specified by iSeg. */
109	RTUINTPTR offSeg;
110	/** Segment number. */
111	RTDBGSEGIDX iSeg;
112	/** Symbol Flags. (reserved). */
113	uint32_t fFlags;
114	/** Symbol ordinal.
115	* This is set to UINT32_MAX if the ordinals aren't supported. */
116	uint32_t iOrdinal;
117	/** Symbol name. */
118	char szName[RTDBG_SYMBOL_NAME_LENGTH];
119	} RTDBGSYMBOL;
120	/** Pointer to debug symbol. */
121	typedef RTDBGSYMBOL *PRTDBGSYMBOL;
122	/** Pointer to const debug symbol. */
123	typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
124
125	/**
126	* Allocate a new symbol structure.
127	*
128	* @returns Pointer to a new structure on success, NULL on failure.
129	*/
130	RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void);
131
132	/**
133	* Duplicates a symbol structure.
134	*
135	* @returns Pointer to duplicate on success, NULL on failure.
136	*
137	* @param pSymInfo The symbol info to duplicate.
138	*/
139	RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymInfo);
140
141	/**
142	* Free a symbol structure previously allocated by a RTDbg method.
143	*
144	* @param pSymInfo The symbol info to free. NULL is ignored.
145	*/
146	RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymInfo);
147
148
149	/** Max length (including '\\0') of a debug info file name. */
150	#define RTDBG_FILE_NAME_LENGTH (260)
151
152
153	/**
154	* Debug line number information.
155	*/
156	typedef struct RTDBGLINE
157	{
158	/** Address.
159	* This depends a bit who you ask. It will be the same as offSeg when you
160	* as RTDbgMod, but the mapping address if you ask RTDbgAs. */
161	RTUINTPTR Address;
162	/** Offset into the segment specified by iSeg. */
163	RTUINTPTR offSeg;
164	/** Segment number. */
165	RTDBGSEGIDX iSeg;
166	/** Line number. */
167	uint32_t uLineNo;
168	/** Symbol ordinal.
169	* This is set to UINT32_MAX if the ordinals aren't supported. */
170	uint32_t iOrdinal;
171	/** Filename. */
172	char szFilename[RTDBG_FILE_NAME_LENGTH];
173	} RTDBGLINE;
174	/** Pointer to debug line number. */
175	typedef RTDBGLINE *PRTDBGLINE;
176	/** Pointer to const debug line number. */
177	typedef const RTDBGLINE *PCRTDBGLINE;
178
179	/**
180	* Allocate a new line number structure.
181	*
182	* @returns Pointer to a new structure on success, NULL on failure.
183	*/
184	RTDECL(PRTDBGLINE) RTDbgLineAlloc(void);
185
186	/**
187	* Duplicates a line number structure.
188	*
189	* @returns Pointer to duplicate on success, NULL on failure.
190	*
191	* @param pLine The line number to duplicate.
192	*/
193	RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);
194
195	/**
196	* Free a line number structure previously allocated by a RTDbg method.
197	*
198	* @param pLine The line number to free. NULL is ignored.
199	*/
200	RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine);
201
202
203	/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
204	* @{
205	*/
206
207	/**
208	* Creates an empty address space.
209	*
210	* @returns IPRT status code.
211	*
212	* @param phDbgAs Where to store the address space handle on success.
213	* @param FirstAddr The first address in the address space.
214	* @param LastAddr The last address in the address space.
215	* @param pszName The name of the address space.
216	*/
217	RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
218
219	/**
220	* Variant of RTDbgAsCreate that takes a name format string.
221	*
222	* @returns IPRT status code.
223	*
224	* @param phDbgAs Where to store the address space handle on success.
225	* @param FirstAddr The first address in the address space.
226	* @param LastAddr The last address in the address space.
227	* @param pszNameFmt The name format of the address space.
228	* @param va Format arguments.
229	*/
230	RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va);
231
232	/**
233	* Variant of RTDbgAsCreate that takes a name format string.
234	*
235	* @returns IPRT status code.
236	*
237	* @param phDbgAs Where to store the address space handle on success.
238	* @param FirstAddr The first address in the address space.
239	* @param LastAddr The last address in the address space.
240	* @param pszNameFmt The name format of the address space.
241	* @param ... Format arguments.
242	*/
243	RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...);
244
245	/**
246	* Retains a reference to the address space.
247	*
248	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
249	*
250	* @param hDbgAs The address space handle.
251	*
252	* @remarks Will not take any locks.
253	*/
254	RTDECL(uint32_t) RTDbgAsRetain(RTDBGAS hDbgAs);
255
256	/**
257	* Release a reference to the address space.
258	*
259	* When the reference count reaches zero, the address space is destroyed.
260	* That means unlinking all the modules it currently contains, potentially
261	* causing some or all of them to be destroyed as they are managed by
262	* reference counting.
263	*
264	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
265	*
266	* @param hDbgAs The address space handle. The NIL handle is quietly
267	* ignored and 0 is returned.
268	*
269	* @remarks Will not take any locks.
270	*/
271	RTDECL(uint32_t) RTDbgAsRelease(RTDBGAS hDbgAs);
272
273	/**
274	* Gets the name of an address space.
275	*
276	* @returns read only address space name.
277	* NULL if hDbgAs is invalid.
278	*
279	* @param hDbgAs The address space handle.
280	*
281	* @remarks Will not take any locks.
282	*/
283	RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
284
285	/**
286	* Gets the first address in an address space.
287	*
288	* @returns The address.
289	* 0 if hDbgAs is invalid.
290	*
291	* @param hDbgAs The address space handle.
292	*
293	* @remarks Will not take any locks.
294	*/
295	RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
296
297	/**
298	* Gets the last address in an address space.
299	*
300	* @returns The address.
301	* 0 if hDbgAs is invalid.
302	*
303	* @param hDbgAs The address space handle.
304	*
305	* @remarks Will not take any locks.
306	*/
307	RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
308
309	/**
310	* Gets the number of modules in the address space.
311	*
312	* This can be used together with RTDbgAsModuleByIndex
313	* to enumerate the modules.
314	*
315	* @returns The number of modules.
316	*
317	* @param hDbgAs The address space handle.
318	*
319	* @remarks Will not take any locks.
320	*/
321	RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
322
323	/** @name Flags for RTDbgAsModuleLink and RTDbgAsModuleLinkSeg
324	* @{ */
325	/** Replace all conflicting module.
326	* (The conflicting modules will be removed the address space and their
327	* references released.) */
328	#define RTDBGASLINK_FLAGS_REPLACE RT_BIT_32(0)
329	/** Mask containing the valid flags. */
330	#define RTDBGASLINK_FLAGS_VALID_MASK UINT32_C(0x00000001)
331	/** @} */
332
333	/**
334	* Links a module into the address space at the give address.
335	*
336	* The size of the mapping is determined using RTDbgModImageSize().
337	*
338	* @returns IPRT status code.
339	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
340	* outside the address space.
341	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
342	*
343	* @param hDbgAs The address space handle.
344	* @param hDbgMod The module handle of the module to be linked in.
345	* @param ImageAddr The address to link the module at.
346	* @param fFlags See RTDBGASLINK_FLAGS_*.
347	*/
348	RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr, uint32_t fFlags);
349
350	/**
351	* Links a segment into the address space at the give address.
352	*
353	* The size of the mapping is determined using RTDbgModSegmentSize().
354	*
355	* @returns IPRT status code.
356	* @retval VERR_OUT_OF_RANGE if the specified address will put the module
357	* outside the address space.
358	* @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
359	*
360	* @param hDbgAs The address space handle.
361	* @param hDbgMod The module handle.
362	* @param iSeg The segment number (0-based) of the segment to be
363	* linked in.
364	* @param SegAddr The address to link the segment at.
365	* @param fFlags See RTDBGASLINK_FLAGS_*.
366	*/
367	RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr, uint32_t fFlags);
368
369	/**
370	* Unlinks all the mappings of a module from the address space.
371	*
372	* @returns IPRT status code.
373	* @retval VERR_NOT_FOUND if the module wasn't found.
374	*
375	* @param hDbgAs The address space handle.
376	* @param hDbgMod The module handle of the module to be unlinked.
377	*/
378	RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
379
380	/**
381	* Unlinks the mapping at the specified address.
382	*
383	* @returns IPRT status code.
384	* @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
385	*
386	* @param hDbgAs The address space handle.
387	* @param Addr The address within the mapping to be unlinked.
388	*/
389	RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
390
391	/**
392	* Get a the handle of a module in the address space by is index.
393	*
394	* @returns A retained handle to the specified module. The caller must release
395	* the returned reference.
396	* NIL_RTDBGMOD if invalid index or handle.
397	*
398	* @param hDbgAs The address space handle.
399	* @param iModule The index of the module to get.
400	*
401	* @remarks The module indexes may change after calls to RTDbgAsModuleLink,
402	* RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
403	* RTDbgAsModuleUnlinkByAddr.
404	*/
405	RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
406
407	/**
408	* Queries mapping module information by handle.
409	*
410	* @returns IPRT status code.
411	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
412	*
413	* @param hDbgAs The address space handle.
414	* @param Addr Address within the mapping of the module or segment.
415	* @param phMod Where to the return the retained module handle.
416	* Optional.
417	* @param pAddr Where to return the base address of the mapping.
418	* Optional.
419	* @param piSeg Where to return the segment index. This is set to
420	* NIL if the entire module is mapped as a single
421	* mapping. Optional.
422	*/
423	RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
424
425	/**
426	* Queries mapping module information by name.
427	*
428	* @returns IPRT status code.
429	* @retval VERR_NOT_FOUND if no mapping was found at the specified address.
430	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
431	*
432	* @param hDbgAs The address space handle.
433	* @param pszName The module name.
434	* @param iName There can be more than one module by the same name
435	* in an address space. This argument indicates which
436	* is meant. (0 based)
437	* @param phMod Where to the return the retained module handle.
438	*/
439	RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
440
441	/**
442	* Information about a mapping.
443	*
444	* This is used by RTDbgAsModuleGetMapByIndex.
445	*/
446	typedef struct RTDBGASMAPINFO
447	{
448	/** The mapping address. */
449	RTUINTPTR Address;
450	/** The segment mapped there.
451	* This is NIL_RTDBGSEGIDX if the entire module image is mapped here. */
452	RTDBGSEGIDX iSeg;
453	} RTDBGASMAPINFO;
454	/** Pointer to info about an address space mapping. */
455	typedef RTDBGASMAPINFO *PRTDBGASMAPINFO;
456	/** Pointer to const info about an address space mapping. */
457	typedef RTDBGASMAPINFO const *PCRTDBGASMAPINFO;
458
459	/**
460	* Queries mapping information for a module given by index.
461	*
462	* @returns IRPT status code.
463	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
464	* @retval VERR_OUT_OF_RANGE if the name index was out of range.
465	* @retval VINF_BUFFER_OVERFLOW if the array is too small and the returned
466	* information is incomplete.
467	*
468	* @param hDbgAs The address space handle.
469	* @param iModule The index of the module to get.
470	* @param paMappings Where to return the mapping information. The buffer
471	* size is given by *pcMappings.
472	* @param pcMappings IN: Size of the paMappings array. OUT: The number of
473	* entries returned.
474	* @param fFlags Flags for reserved for future use. MBZ.
475	*
476	* @remarks See remarks for RTDbgAsModuleByIndex regarding the volatility of the
477	* iModule parameter.
478	*/
479	RTDECL(int) RTDbgAsModuleQueryMapByIndex(RTDBGAS hDbgAs, uint32_t iModule, PRTDBGASMAPINFO paMappings, uint32_t *pcMappings, uint32_t fFlags);
480
481	/**
482	* Adds a symbol to a module in the address space.
483	*
484	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
485	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
486	* @retval VERR_NOT_FOUND if no module was found at the specified address.
487	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
488	* custom symbols.
489	*
490	* @param hDbgAs The address space handle.
491	* @param pszSymbol The symbol name.
492	* @param Addr The address of the symbol.
493	* @param cb The size of the symbol.
494	* @param fFlags Symbol flags.
495	* @param piOrdinal Where to return the symbol ordinal on success. If
496	* the interpreter doesn't do ordinals, this will be set to
497	* UINT32_MAX. Optional
498	*/
499	RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char pszSymbol, RTUINTPTR Addr, RTUINTPTR cb, uint32_t fFlags, uint32_t piOrdinal);
500
501	/**
502	* Query a symbol by address.
503	*
504	* @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
505	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
506	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
507	*
508	* @param hDbgAs The address space handle.
509	* @param Addr The address which closest symbol is requested.
510	* @param poffDisp Where to return the distance between the symbol
511	* and address. Optional.
512	* @param pSymbol Where to return the symbol info.
513	* @param phMod Where to return the module handle. Optional.
514	*/
515	RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
516
517	/**
518	* Query a symbol by address.
519	*
520	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
521	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
522	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
523	*
524	* @param hDbgAs The address space handle.
525	* @param Addr The address which closest symbol is requested.
526	* @param poffDisp Where to return the distance between the symbol
527	* and address. Optional.
528	* @param ppSymInfo Where to return the pointer to the allocated symbol
529	* info. Always set. Free with RTDbgSymbolFree.
530	* @param phMod Where to return the module handle. Optional.
531	*/
532	RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo, PRTDBGMOD phMod);
533
534	/**
535	* Query a symbol by name.
536	*
537	* @returns IPRT status code.
538	* @retval VERR_SYMBOL_NOT_FOUND if not found.
539	*
540	* @param hDbgAs The address space handle.
541	* @param pszSymbol The symbol name. It is possible to limit the scope
542	* of the search by prefixing the symbol with a module
543	* name pattern followed by a bang (!) character.
544	* RTStrSimplePatternNMatch is used for the matching.
545	* @param pSymbol Where to return the symbol info.
546	* @param phMod Where to return the module handle. Optional.
547	*/
548	RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
549
550	/**
551	* Query a symbol by name, allocating the returned symbol structure.
552	*
553	* @returns IPRT status code.
554	* @retval VERR_SYMBOL_NOT_FOUND if not found.
555	*
556	* @param hDbgAs The address space handle.
557	* @param pszSymbol The symbol name. See RTDbgAsSymbolByName for more.
558	* @param ppSymbol Where to return the pointer to the allocated
559	* symbol info. Always set. Free with RTDbgSymbolFree.
560	* @param phMod Where to return the module handle. Optional.
561	*/
562	RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char pszSymbol, PRTDBGSYMBOL ppSymbol, PRTDBGMOD phMod);
563
564	/**
565	* Query a line number by address.
566	*
567	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
568	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
569	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
570	*
571	* @param hDbgAs The address space handle.
572	* @param Addr The address which closest symbol is requested.
573	* @param poffDisp Where to return the distance between the line
574	* number and address.
575	* @param pLine Where to return the line number information.
576	*/
577	RTDECL(int) RTDbgAs(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
578
579	/**
580	* Adds a line number to a module in the address space.
581	*
582	* @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
583	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
584	* @retval VERR_NOT_FOUND if no module was found at the specified address.
585	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
586	* custom symbols.
587	*
588	* @param hDbgAs The address space handle.
589	* @param pszFile The file name.
590	* @param uLineNo The line number.
591	* @param Addr The address of the symbol.
592	* @param piOrdinal Where to return the line number ordinal on success.
593	* If the interpreter doesn't do ordinals, this will be
594	* set to UINT32_MAX. Optional.
595	*/
596	RTDECL(int) RTDbgAsLineAdd(RTDBGAS hDbgAs, const char pszFile, uint32_t uLineNo, RTUINTPTR Addr, uint32_t piOrdinal);
597
598
599	/**
600	* Query a line number by address.
601	*
602	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
603	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
604	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
605	*
606	* @param hDbgAs The address space handle.
607	* @param Addr The address which closest symbol is requested.
608	* @param poffDisp Where to return the distance between the line
609	* number and address.
610	* @param pLine Where to return the line number information.
611	*/
612	RTDECL(int) RTDbgAsLineByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
613
614	/**
615	* Query a line number by address.
616	*
617	* @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
618	* @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
619	* @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
620	*
621	* @param hDbgAs The address space handle.
622	* @param Addr The address which closest symbol is requested.
623	* @param poffDisp Where to return the distance between the line
624	* number and address.
625	* @param ppLine Where to return the pointer to the allocated line
626	* number info. Always set. Free with RTDbgLineFree.
627	*/
628	RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
629
630	/** @todo Missing some bits here. */
631
632	/** @} */
633
634
635	/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
636	* @{
637	*/
638
639	/**
640	* Creates a module based on the default debug info container.
641	*
642	* This can be used to manually load a module and its symbol. The primary user
643	* group is the debug info interpreters, which use this API to create an
644	* efficient debug info container behind the scenes and forward all queries to
645	* it once the info has been loaded.
646	*
647	* @returns IPRT status code.
648	*
649	* @param phDbgMod Where to return the module handle.
650	* @param pszName The name of the module (mandatory).
651	* @param cbSeg The size of initial segment. If zero, segments will
652	* have to be added manually using RTDbgModSegmentAdd.
653	* @param fFlags Flags reserved for future extensions, MBZ for now.
654	*/
655	RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, RTUINTPTR cbSeg, uint32_t fFlags);
656
657	RTDECL(int) RTDbgModCreateDeferred(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR cb, uint32_t fFlags);
658	RTDECL(int) RTDbgModCreateFromImage(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, uint32_t fFlags);
659	RTDECL(int) RTDbgModCreateFromMap(PRTDBGMOD phDbgMod, const char pszFilename, const char pszName, RTUINTPTR uSubtrahend, uint32_t fFlags);
660
661
662	/**
663	* Retains another reference to the module.
664	*
665	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
666	*
667	* @param hDbgMod The module handle.
668	*
669	* @remarks Will not take any locks.
670	*/
671	RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
672
673	/**
674	* Release a reference to the module.
675	*
676	* When the reference count reaches zero, the module is destroyed.
677	*
678	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
679	*
680	* @param hDbgMod The module handle. The NIL handle is quietly ignored
681	* and 0 is returned.
682	*
683	* @remarks Will not take any locks.
684	*/
685	RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
686
687	/**
688	* Gets the module name.
689	*
690	* @returns Pointer to a read only string containing the name.
691	*
692	* @param hDbgMod The module handle.
693	*/
694	RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
695
696	/**
697	* Converts an image relative address to a segment:offset address.
698	*
699	* @returns Segment index on success.
700	* NIL_RTDBGSEGIDX is returned if the module handle or the RVA are
701	* invalid.
702	*
703	* @param hDbgMod The module handle.
704	* @param uRva The image relative address to convert.
705	* @param poffSeg Where to return the segment offset. Optional.
706	*/
707	RTDECL(RTDBGSEGIDX) RTDbgModRvaToSegOff(RTDBGMOD hDbgMod, RTUINTPTR uRva, PRTUINTPTR poffSeg);
708
709	/**
710	* Image size when mapped if segments are mapped adjacently.
711	*
712	* For ELF, PE, and Mach-O images this is (usually) a natural query, for LX and
713	* NE and such it's a bit odder and the answer may not make much sense for them.
714	*
715	* @returns Image mapped size.
716	* RTUINTPTR_MAX is returned if the handle is invalid.
717	*
718	* @param hDbgMod The module handle.
719	*/
720	RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
721
722	/**
723	* Gets the module tag value if any.
724	*
725	* @returns The tag. 0 if hDbgMod is invalid.
726	*
727	* @param hDbgMod The module handle.
728	*/
729	RTDECL(uint64_t) RTDbgModGetTag(RTDBGMOD hDbgMod);
730
731	/**
732	* Tags or untags the module.
733	*
734	* @returns IPRT status code.
735	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
736	*
737	* @param hDbgMod The module handle.
738	* @param uTag The tag value. The convention is that 0 is no tag
739	* and any other value means it's tagged. It's adviced
740	* to use some kind of unique number like an address
741	* (global or string cache for instance) to avoid
742	* collisions with other users
743	*/
744	RTDECL(int) RTDbgModSetTag(RTDBGMOD hDbgMod, uint64_t uTag);
745
746
747	/**
748	* Adds a segment to the module. Optional feature.
749	*
750	* This method is intended used for manually constructing debug info for a
751	* module. The main usage is from other debug info interpreters that want to
752	* avoid writing a debug info database and instead uses the standard container
753	* behind the scenes.
754	*
755	* @returns IPRT status code.
756	* @retval VERR_NOT_SUPPORTED if this feature isn't support by the debug info
757	* interpreter. This is a common return code.
758	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
759	* @retval VERR_DBG_ADDRESS_WRAP if uRva+cb wraps around.
760	* @retval VERR_DBG_SEGMENT_NAME_OUT_OF_RANGE if pszName is too short or long.
761	* @retval VERR_INVALID_PARAMETER if fFlags contains undefined flags.
762	* @retval VERR_DBG_SPECIAL_SEGMENT if *piSeg is a special segment.
763	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if *piSeg doesn't meet expectations.
764	*
765	* @param hDbgMod The module handle.
766	* @param uRva The image relative address of the segment.
767	* @param cb The size of the segment.
768	* @param pszName The segment name. Does not normally need to be
769	* unique, although this is somewhat up to the
770	* debug interpreter to decide.
771	* @param fFlags Segment flags. Reserved for future used, MBZ.
772	* @param piSeg The segment index or NIL_RTDBGSEGIDX on input.
773	* The assigned segment index on successful return.
774	* Optional.
775	*/
776	RTDECL(int) RTDbgModSegmentAdd(RTDBGMOD hDbgMod, RTUINTPTR uRva, RTUINTPTR cb, const char *pszName,
777	uint32_t fFlags, PRTDBGSEGIDX piSeg);
778
779	/**
780	* Gets the number of segments in the module.
781	*
782	* This is can be used to determine the range which can be passed to
783	* RTDbgModSegmentByIndex and derivates.
784	*
785	* @returns The segment relative address.
786	* NIL_RTDBGSEGIDX if the handle is invalid.
787	*
788	* @param hDbgMod The module handle.
789	*/
790	RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
791
792	/**
793	* Query information about a segment.
794	*
795	* This can be used together with RTDbgModSegmentCount to enumerate segments.
796	* The index starts a 0 and stops one below RTDbgModSegmentCount.
797	*
798	* @returns IPRT status code.
799	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if iSeg is too high.
800	* @retval VERR_DBG_SPECIAL_SEGMENT if iSeg indicates a special segment.
801	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
802	*
803	* @param hDbgMod The module handle.
804	* @param iSeg The segment index. No special segments.
805	* @param pSegInfo Where to return the segment info. The
806	* RTDBGSEGMENT::Address member will be set to
807	* RTUINTPTR_MAX or the load address used at link time.
808	*/
809	RTDECL(int) RTDbgModSegmentByIndex(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, PRTDBGSEGMENT pSegInfo);
810
811	/**
812	* Gets the size of a segment.
813	*
814	* This is a just a wrapper around RTDbgModSegmentByIndex.
815	*
816	* @returns The segment size.
817	* RTUINTPTR_MAX is returned if either the handle and segment index are
818	* invalid.
819	*
820	* @param hDbgMod The module handle.
821	* @param iSeg The segment index. RTDBGSEGIDX_ABS is not allowed.
822	* If RTDBGSEGIDX_RVA is used, the functions returns
823	* the same value as RTDbgModImageSize.
824	*/
825	RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
826
827	/**
828	* Gets the image relative address of a segment.
829	*
830	* This is a just a wrapper around RTDbgModSegmentByIndex.
831	*
832	* @returns The segment relative address.
833	* RTUINTPTR_MAX is returned if either the handle and segment index are
834	* invalid.
835	*
836	* @param hDbgMod The module handle.
837	* @param iSeg The segment index. No special segment indexes
838	* allowed (asserted).
839	*/
840	RTDECL(RTUINTPTR) RTDbgModSegmentRva(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
841
842
843	/**
844	* Adds a line number to the module.
845	*
846	* @returns IPRT status code.
847	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
848	* custom symbols. This is a common place occurrence.
849	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
850	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
851	* short.
852	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
853	* it's not inside any of the segments defined by the module.
854	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
855	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
856	* end of the segment.
857	* @retval VERR_DBG_ADDRESS_WRAP if off+cb wraps around.
858	* @retval VERR_INVALID_PARAMETER if the symbol flags sets undefined bits.
859	*
860	* @param hDbgMod The module handle.
861	* @param pszSymbol The symbol name.
862	* @param iSeg The segment index.
863	* @param off The segment offset.
864	* @param cb The size of the symbol. Can be zero, although this
865	* may depend somewhat on the debug interpreter.
866	* @param fFlags Symbol flags. Reserved for the future, MBZ.
867	* @param piOrdinal Where to return the symbol ordinal on success. If
868	* the interpreter doesn't do ordinals, this will be set to
869	* UINT32_MAX. Optional.
870	*/
871	RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off,
872	RTUINTPTR cb, uint32_t fFlags, uint32_t *piOrdinal);
873
874	/**
875	* Gets the symbol count.
876	*
877	* This can be used together wtih RTDbgModSymbolByOrdinal or
878	* RTDbgModSymbolByOrdinalA to enumerate all the symbols.
879	*
880	* @returns The number of symbols in the module.
881	* UINT32_MAX is returned if the module handle is invalid or some other
882	* error occurs.
883	*
884	* @param hDbgMod The module handle.
885	*/
886	RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
887
888	/**
889	* Queries symbol information by ordinal number.
890	*
891	* @returns IPRT status code.
892	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
893	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
894	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
895	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
896	*
897	* @param hDbgMod The module handle.
898	* @param iOrdinal The symbol ordinal number. 0-based. The highest
899	* number is RTDbgModSymbolCount() - 1.
900	* @param pSymInfo Where to store the symbol information.
901	*/
902	RTDECL(int) RTDbgModSymbolByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL pSymInfo);
903
904	/**
905	* Queries symbol information by ordinal number.
906	*
907	* @returns IPRT status code.
908	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
909	* @retval VERR_NOT_SUPPORTED if lookup by ordinal is not supported.
910	* @retval VERR_SYMBOL_NOT_FOUND if there is no symbol at the given number.
911	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
912	*
913	* @param hDbgMod The module handle.
914	* @param iOrdinal The symbol ordinal number. 0-based. The highest
915	* number is RTDbgModSymbolCount() - 1.
916	* @param ppSymInfo Where to store the pointer to the returned
917	* symbol information. Always set. Free with
918	* RTDbgSymbolFree.
919	*/
920	RTDECL(int) RTDbgModSymbolByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGSYMBOL *ppSymInfo);
921
922	/**
923	* Queries symbol information by address.
924	*
925	* The returned symbol is what the debug info interpreter considers the symbol
926	* most applicable to the specified address. This usually means a symbol with an
927	* address equal or lower than the requested.
928	*
929	* @returns IPRT status code.
930	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
931	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
932	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
933	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
934	* it's not inside any of the segments defined by the module.
935	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
936	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
937	* end of the segment.
938	*
939	* @param hDbgMod The module handle.
940	* @param iSeg The segment number.
941	* @param off The offset into the segment.
942	* @param poffDisp Where to store the distance between the
943	* specified address and the returned symbol.
944	* Optional.
945	* @param pSymInfo Where to store the symbol information.
946	*/
947	RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymInfo);
948
949	/**
950	* Queries symbol information by address.
951	*
952	* The returned symbol is what the debug info interpreter considers the symbol
953	* most applicable to the specified address. This usually means a symbol with an
954	* address equal or lower than the requested.
955	*
956	* @returns IPRT status code.
957	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
958	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
959	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
960	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
961	* it's not inside any of the segments defined by the module.
962	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
963	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
964	* end of the segment.
965	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
966	*
967	* @param hDbgMod The module handle.
968	* @param iSeg The segment index.
969	* @param off The offset into the segment.
970	* @param poffDisp Where to store the distance between the
971	* specified address and the returned symbol. Optional.
972	* @param ppSymInfo Where to store the pointer to the returned
973	* symbol information. Always set. Free with
974	* RTDbgSymbolFree.
975	*/
976	RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymInfo);
977
978	/**
979	* Queries symbol information by symbol name.
980	*
981	* @returns IPRT status code.
982	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
983	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
984	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
985	* short.
986	*
987	* @param hDbgMod The module handle.
988	* @param pszSymbol The symbol name.
989	* @param pSymInfo Where to store the symbol information.
990	*/
991	RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymInfo);
992
993	/**
994	* Queries symbol information by symbol name.
995	*
996	* @returns IPRT status code.
997	* @retval VERR_DBG_NO_SYMBOLS if there aren't any symbols.
998	* @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
999	* @retval VERR_DBG_SYMBOL_NAME_OUT_OF_RANGE if the symbol name is too long or
1000	* short.
1001	* @retval VERR_NO_MEMORY if RTDbgSymbolAlloc fails.
1002	*
1003	* @param hDbgMod The module handle.
1004	* @param pszSymbol The symbol name.
1005	* @param ppSymInfo Where to store the pointer to the returned
1006	* symbol information. Always set. Free with
1007	* RTDbgSymbolFree.
1008	*/
1009	RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char pszSymbol, PRTDBGSYMBOL ppSymInfo);
1010
1011	/**
1012	* Adds a line number to the module.
1013	*
1014	* @returns IPRT status code.
1015	* @retval VERR_NOT_SUPPORTED if the module interpret doesn't support adding
1016	* custom symbols. This should be consider a normal response.
1017	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1018	* @retval VERR_DBG_FILE_NAME_OUT_OF_RANGE if the file name is too longer or
1019	* empty.
1020	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1021	* it's not inside any of the segments defined by the module.
1022	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1023	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1024	* end of the segment.
1025	* @retval VERR_INVALID_PARAMETER if the line number flags sets undefined bits.
1026	*
1027	* @param hDbgMod The module handle.
1028	* @param pszFile The file name.
1029	* @param uLineNo The line number.
1030	* @param iSeg The segment index.
1031	* @param off The segment offset.
1032	* @param piOrdinal Where to return the line number ordinal on
1033	* success. If the interpreter doesn't do ordinals,
1034	* this will be set to UINT32_MAX. Optional.
1035	*/
1036	RTDECL(int) RTDbgModLineAdd(RTDBGMOD hDbgMod, const char *pszFile, uint32_t uLineNo,
1037	RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t *piOrdinal);
1038
1039	/**
1040	* Gets the line number count.
1041	*
1042	* This can be used together wtih RTDbgModLineByOrdinal or RTDbgModSymbolByLineA
1043	* to enumerate all the line number information.
1044	*
1045	* @returns The number of line numbers in the module.
1046	* UINT32_MAX is returned if the module handle is invalid or some other
1047	* error occurs.
1048	*
1049	* @param hDbgMod The module handle.
1050	*/
1051	RTDECL(uint32_t) RTDbgModLineCount(RTDBGMOD hDbgMod);
1052
1053	/**
1054	* Queries line number information by ordinal number.
1055	*
1056	* This can be used to enumerate the line numbers for the module. Use
1057	* RTDbgModLineCount() to figure the end of the ordinals.
1058	*
1059	* @returns IPRT status code.
1060	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1061	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1062	* ordinal.
1063	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1064
1065	* @param hDbgMod The module handle.
1066	* @param iOrdinal The line number ordinal number.
1067	* @param pLineInfo Where to store the information about the line
1068	* number.
1069	*/
1070	RTDECL(int) RTDbgModLineByOrdinal(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE pLineInfo);
1071
1072	/**
1073	* Queries line number information by ordinal number.
1074	*
1075	* This can be used to enumerate the line numbers for the module. Use
1076	* RTDbgModLineCount() to figure the end of the ordinals.
1077	*
1078	* @returns IPRT status code.
1079	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1080	* @retval VERR_DBG_LINE_NOT_FOUND if there is no line number with that
1081	* ordinal.
1082	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1083	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1084	*
1085	* @param hDbgMod The module handle.
1086	* @param iOrdinal The line number ordinal number.
1087	* @param ppLineInfo Where to store the pointer to the returned line
1088	* number information. Always set. Free with
1089	* RTDbgLineFree.
1090	*/
1091	RTDECL(int) RTDbgModLineByOrdinalA(RTDBGMOD hDbgMod, uint32_t iOrdinal, PRTDBGLINE *ppLineInfo);
1092
1093	/**
1094	* Queries line number information by address.
1095	*
1096	* The returned line number is what the debug info interpreter considers the
1097	* one most applicable to the specified address. This usually means a line
1098	* number with an address equal or lower than the requested.
1099	*
1100	* @returns IPRT status code.
1101	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1102	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1103	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1104	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1105	* it's not inside any of the segments defined by the module.
1106	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1107	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1108	* end of the segment.
1109	*
1110	* @param hDbgMod The module handle.
1111	* @param iSeg The segment number.
1112	* @param off The offset into the segment.
1113	* @param poffDisp Where to store the distance between the
1114	* specified address and the returned symbol.
1115	* Optional.
1116	* @param pLineInfo Where to store the line number information.
1117	*/
1118	RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLineInfo);
1119
1120	/**
1121	* Queries line number information by address.
1122	*
1123	* The returned line number is what the debug info interpreter considers the
1124	* one most applicable to the specified address. This usually means a line
1125	* number with an address equal or lower than the requested.
1126	*
1127	* @returns IPRT status code.
1128	* @retval VERR_DBG_NO_LINE_NUMBERS if there aren't any line numbers.
1129	* @retval VERR_DBG_LINE_NOT_FOUND if no suitable line number was found.
1130	* @retval VERR_INVALID_HANDLE if hDbgMod is invalid.
1131	* @retval VERR_DBG_INVALID_RVA if an image relative address is specified and
1132	* it's not inside any of the segments defined by the module.
1133	* @retval VERR_DBG_INVALID_SEGMENT_INDEX if the segment index isn't valid.
1134	* @retval VERR_DBG_INVALID_SEGMENT_OFFSET if the segment offset is beyond the
1135	* end of the segment.
1136	* @retval VERR_NO_MEMORY if RTDbgLineAlloc fails.
1137	*
1138	* @param hDbgMod The module handle.
1139	* @param iSeg The segment number.
1140	* @param off The offset into the segment.
1141	* @param poffDisp Where to store the distance between the
1142	* specified address and the returned symbol.
1143	* Optional.
1144	* @param ppLineInfo Where to store the pointer to the returned line
1145	* number information. Always set. Free with
1146	* RTDbgLineFree.
1147	*/
1148	RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLineInfo);
1149	/** @} */
1150
1151	# endif /* IN_RING3 */
1152
1153
1154	/** @name Kernel Debug Info API
1155	*
1156	* This is a specialized API for obtaining symbols and structure information
1157	* about the running kernel. It is relatively OS specific. Its purpose and
1158	* operation is doesn't map all that well onto RTDbgMod, so a few dedicated
1159	* functions was created for it.
1160	*
1161	* @{ */
1162
1163	/** Handle to the kernel debug info. */
1164	typedef struct RTDBGKRNLINFOINT *RTDBGKRNLINFO;
1165	/** Pointer to a kernel debug info handle. */
1166	typedef RTDBGKRNLINFO *PRTDBGKRNLINFO;
1167	/** Nil kernel debug info handle. */
1168	#define NIL_RTDBGKRNLINFO ((RTDBGKRNLINFO)0)
1169
1170	/**
1171	* Opens the kernel debug info.
1172	*
1173	* @returns IPRT status code. Can fail for any number of reasons.
1174	*
1175	* @param phKrnlInfo Where to return the kernel debug info handle on
1176	* success.
1177	* @param fFlags Flags reserved for future use. Must be zero.
1178	*/
1179	RTR0DECL(int) RTR0DbgKrnlInfoOpen(PRTDBGKRNLINFO phKrnlInfo, uint32_t fFlags);
1180
1181	/**
1182	* Retains a reference to the kernel debug info handle.
1183	*
1184	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
1185	* @param hKrnlInfo The kernel info handle.
1186	*/
1187	RTR0DECL(uint32_t) RTR0DbgKrnlInfoRetain(RTDBGKRNLINFO hKrnlInfo);
1188
1189
1190	/**
1191	* Releases a reference to the kernel debug info handle, destroying it when the
1192	* counter reaches zero.
1193	*
1194	* @returns New reference count, UINT32_MAX on invalid handle (asserted).
1195	* @param hKrnlInfo The kernel info handle. NIL_RTDBGKRNLINFO is
1196	* quietly ignored.
1197	*/
1198	RTR0DECL(uint32_t) RTR0DbgKrnlInfoRelease(RTDBGKRNLINFO hKrnlInfo);
1199
1200	/**
1201	* Queries the offset (in bytes) of a member of a kernel structure.
1202	*
1203	* @returns IPRT status code.
1204	* @retval VINF_SUCCESS and offset at @a poffMember.
1205	* @retval VERR_NOT_FOUND if the structure or the member was not found.
1206	* @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1207	* @retval VERR_INVALID_POINTER if any of the pointers are bad.
1208	*
1209	* @param hKrnlInfo The kernel info handle.
1210	* @param pszStructure The structure name.
1211	* @param pszMember The member name.
1212	* @param poffMember Where to return the offset.
1213	*/
1214	RTR0DECL(int) RTR0DbgKrnlInfoQueryMember(RTDBGKRNLINFO hKrnlInfo, const char *pszStructure,
1215	const char pszMember, size_t poffMember);
1216
1217
1218	/**
1219	* Queries the value (usually the address) of a kernel symbol.
1220	*
1221	* This may go looking for the symbol in other modules, in which case it will
1222	* always check the kernel symbol table first.
1223	*
1224	* @returns IPRT status code.
1225	* @retval VINF_SUCCESS and value at @a ppvSymbol.
1226	* @retval VERR_SYMBOL_NOT_FOUND
1227	* @retval VERR_INVALID_HANDLE if hKrnlInfo is bad.
1228	* @retval VERR_INVALID_POINTER if any of the pointers are bad.
1229	*
1230	* @param hKrnlInfo The kernel info handle.
1231	* @param pszModule Reserved for future extensions. Pass NULL.
1232	* @param pszSymbol The C name of the symbol.
1233	* @param ppvSymbol Where to return the symbol value, passing NULL is
1234	* OK. This may be modified even on failure, in
1235	* particular, it will be set to NULL when
1236	* VERR_SYMBOL_NOT_FOUND is returned.
1237	*
1238	* @sa RTLdrGetSymbol.
1239	*/
1240	RTR0DECL(int) RTR0DbgKrnlInfoQuerySymbol(RTDBGKRNLINFO hKrnlInfo, const char *pszModule,
1241	const char pszSymbol, void *ppvSymbol);
1242	/** @} */
1243
1244	/** @} */
1245
1246	RT_C_DECLS_END
1247
1248	#endif
1249

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

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

Download in other formats: