dbg.h@ 44528

Last change on this file since 44528 was 44528, checked in by vboxsync, 12 years ago
header (C) fixes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 49.7 KB

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

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

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

Download in other formats: