VirtualBox

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

Last change on this file since 19561 was 19561, checked in by vboxsync, 16 years ago

build fix.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 16.2 KB
Line 
1/* $Id: dbg.h 19561 2009-05-10 05:20:01Z vboxsync $ */
2/** @file
3 * IPRT - Debugging Routines.
4 */
5
6/*
7 * Copyright (C) 2008-2009 Sun Microsystems, Inc.
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 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
18 * Clara, CA 95054 USA or visit http://www.sun.com if you need
19 * additional information or have any questions.
20 */
21
22#ifndef ___iprt_dbg_h
23#define ___iprt_dbg_h
24
25#include <iprt/types.h>
26#include <iprt/stdarg.h>
27
28__BEGIN_DECLS
29
30/** @defgroup grp_rt_dbg RTDbg - Debugging Routines
31 * @ingroup grp_rt
32 * @{
33 */
34
35
36/** Debug segment index. */
37typedef uint32_t RTDBGSEGIDX;
38/** Pointer to a debug segment index. */
39typedef RTDBGSEGIDX *PRTDBGSEGIDX;
40/** Pointer to a const debug segment index. */
41typedef RTDBGSEGIDX const *PCRTDBGSEGIDX;
42/** NIL debug segment index. */
43#define NIL_RTDBGSEGIDX UINT32_C(0xffffffff)
44/** Special segment index that indicates that the offset is a relative
45 * virtual address (RVA). I.e. an offset from the start of the module. */
46#define RTDBGSEGIDX_RVA UINT32_C(0xfffffff0)
47/** Special segment index that indicates that the offset is a absolute. */
48#define RTDBGSEGIDX_ABS UINT32_C(0xfffffff1)
49
50/** Max length (including '\\0') of a symbol name. */
51#define RTDBG_SYMBOL_NAME_LENGTH (512 - 8 - 4 - 4 - 4)
52
53/**
54 * Debug symbol.
55 */
56typedef struct RTDBGSYMBOL
57{
58 /** Symbol value (address). */
59 RTUINTPTR Value;
60 /** Segment number when applicable or NIL_RTDBGSEGIDX. */
61 RTDBGSEGIDX iSeg;
62 /** Symbol size. */
63 uint32_t cb;
64 /** Symbol Flags. (reserved). */
65 uint32_t fFlags;
66 /** Symbol name. */
67 char szName[RTDBG_SYMBOL_NAME_LENGTH];
68} RTDBGSYMBOL;
69/** Pointer to debug symbol. */
70typedef RTDBGSYMBOL *PRTDBGSYMBOL;
71/** Pointer to const debug symbol. */
72typedef const RTDBGSYMBOL *PCRTDBGSYMBOL;
73
74RTDECL(PRTDBGSYMBOL) RTDbgSymbolAlloc(void);
75RTDECL(PRTDBGSYMBOL) RTDbgSymbolDup(PCRTDBGSYMBOL pSymbol);
76RTDECL(void) RTDbgSymbolFree(PRTDBGSYMBOL pSymbol);
77
78
79/**
80 * Debug line number information.
81 */
82typedef struct RTDBGLINE
83{
84 /** Address. */
85 RTUINTPTR Address;
86 /** Segment number when applicable or NIL_RTDBGSEGIDX. */
87 RTDBGSEGIDX iSeg;
88 /** Line number. */
89 uint32_t uLineNo;
90 /** Filename. */
91 char szFilename[260];
92} RTDBGLINE;
93/** Pointer to debug line number. */
94typedef RTDBGLINE *PRTDBGLINE;
95/** Pointer to const debug line number. */
96typedef const RTDBGLINE *PCRTDBGLINE;
97
98RTDECL(PRTDBGLINE) RTDbgLineAlloc(void);
99RTDECL(PRTDBGLINE) RTDbgLineDup(PCRTDBGLINE pLine);
100RTDECL(void) RTDbgLineFree(PRTDBGLINE pLine);
101
102
103/** @defgroup grp_rt_dbgas RTDbgAs - Debug Address Space
104 * @{
105 */
106
107/**
108 * Creates an empty address space.
109 *
110 * @returns IPRT status code.
111 *
112 * @param phDbgAs Where to store the address space handle on success.
113 * @param FirstAddr The first address in the address space.
114 * @param LastAddr The last address in the address space.
115 * @param pszName The name of the address space.
116 */
117RTDECL(int) RTDbgAsCreate(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszName);
118
119/**
120 * Variant of RTDbgAsCreate that takes a name format string.
121 *
122 * @returns IPRT status code.
123 *
124 * @param phDbgAs Where to store the address space handle on success.
125 * @param FirstAddr The first address in the address space.
126 * @param LastAddr The last address in the address space.
127 * @param pszNameFmt The name format of the address space.
128 * @param va Format arguments.
129 */
130RTDECL(int) RTDbgAsCreateV(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, va_list va);
131
132/**
133 * Variant of RTDbgAsCreate that takes a name format string.
134 *
135 * @returns IPRT status code.
136 *
137 * @param phDbgAs Where to store the address space handle on success.
138 * @param FirstAddr The first address in the address space.
139 * @param LastAddr The last address in the address space.
140 * @param pszNameFmt The name format of the address space.
141 * @param ... Format arguments.
142 */
143RTDECL(int) RTDbgAsCreateF(PRTDBGAS phDbgAs, RTUINTPTR FirstAddr, RTUINTPTR LastAddr, const char *pszNameFmt, ...);
144
145/**
146 * Destroys the address space.
147 *
148 * This means unlinking all the modules it currently contains, potentially
149 * causing some or all of them to be destroyed as they are managed by
150 * reference counting.
151 *
152 * @returns IPRT status code.
153 *
154 * @param hDbgAs The address space handle. A NIL handle will
155 * be quietly ignored.
156 */
157RTDECL(int) RTDbgAsDestroy(RTDBGAS hDbgAs);
158
159/**
160 * Gets the name of an address space.
161 *
162 * @returns read only address space name.
163 * NULL if hDbgAs is invalid.
164 *
165 * @param hDbgAs The address space handle.
166 */
167RTDECL(const char *) RTDbgAsName(RTDBGAS hDbgAs);
168
169/**
170 * Gets the first address in an address space.
171 *
172 * @returns The address.
173 * 0 if hDbgAs is invalid.
174 *
175 * @param hDbgAs The address space handle.
176 */
177RTDECL(RTUINTPTR) RTDbgAsFirstAddr(RTDBGAS hDbgAs);
178
179/**
180 * Gets the last address in an address space.
181 *
182 * @returns The address.
183 * 0 if hDbgAs is invalid.
184 *
185 * @param hDbgAs The address space handle.
186 */
187RTDECL(RTUINTPTR) RTDbgAsLastAddr(RTDBGAS hDbgAs);
188
189/**
190 * Gets the number of modules in the address space.
191 *
192 * This can be used together with RTDbgAsModuleByIndex
193 * to enumerate the modules.
194 *
195 * @returns The number of modules.
196 *
197 * @param hDbgAs The address space handle.
198 */
199RTDECL(uint32_t) RTDbgAsModuleCount(RTDBGAS hDbgAs);
200
201/**
202 * Links a module into the address space at the give address.
203 *
204 * The size of the mapping is determined using RTDbgModImageSize().
205 *
206 * @returns IPRT status code.
207 * @retval VERR_OUT_OF_RANGE if the specified address will put the module
208 * outside the address space.
209 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
210 *
211 * @param hDbgAs The address space handle.
212 * @param hDbgMod The module handle of the module to be linked in.
213 * @param ImageAddr The address to link the module at.
214 */
215RTDECL(int) RTDbgAsModuleLink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTUINTPTR ImageAddr);
216
217/**
218 * Links a segment into the address space at the give address.
219 *
220 * The size of the mapping is determined using RTDbgModSegmentSize().
221 *
222 * @returns IPRT status code.
223 * @retval VERR_OUT_OF_RANGE if the specified address will put the module
224 * outside the address space.
225 * @retval VERR_ADDRESS_CONFLICT if the mapping clashes with existing mappings.
226 *
227 * @param hDbgAs The address space handle.
228 * @param hDbgMod The module handle.
229 * @param iSeg The segment number (0-based) of the segment to be
230 * linked in.
231 * @param SegAddr The address to link the segment at.
232 */
233RTDECL(int) RTDbgAsModuleLinkSeg(RTDBGAS hDbgAs, RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR SegAddr);
234
235/**
236 * Unlinks all the mappings of a module from the address space.
237 *
238 * @returns IPRT status code.
239 * @retval VERR_NOT_FOUND if the module wasn't found.
240 *
241 * @param hDbgAs The address space handle.
242 * @param hDbgMod The module handle of the module to be unlinked.
243 */
244RTDECL(int) RTDbgAsModuleUnlink(RTDBGAS hDbgAs, RTDBGMOD hDbgMod);
245
246/**
247 * Unlinks the mapping at the specified address.
248 *
249 * @returns IPRT status code.
250 * @retval VERR_NOT_FOUND if no module or segment is mapped at that address.
251 *
252 * @param hDbgAs The address space handle.
253 * @param Addr The address within the mapping to be unlinked.
254 */
255RTDECL(int) RTDbgAsModuleUnlinkByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr);
256
257/**
258 * Get a the handle of a module in the address space by is index.
259 *
260 * @returns A retained handle to the specified module. The caller must release
261 * the returned reference.
262 * NIL_RTDBGMOD if invalid index or handle.
263 *
264 * @param hDbgAs The address space handle.
265 * @param iModule The index of the module to get.
266 *
267 * @remarks The module indexes may change after calls to RTDbgAsModuleLink,
268 * RTDbgAsModuleLinkSeg, RTDbgAsModuleUnlink and
269 * RTDbgAsModuleUnlinkByAddr.
270 */
271RTDECL(RTDBGMOD) RTDbgAsModuleByIndex(RTDBGAS hDbgAs, uint32_t iModule);
272
273/**
274 * Queries mapping module information by handle.
275 *
276 * @returns IPRT status code.
277 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.
278 *
279 * @param hDbgAs The address space handle.
280 * @param Addr Address within the mapping of the module or segment.
281 * @param phMod Where to the return the retained module handle.
282 * Optional.
283 * @param pAddr Where to return the base address of the mapping.
284 * Optional.
285 * @param piSeg Where to return the segment index. This is set to
286 * NIL if the entire module is mapped as a single
287 * mapping. Optional.
288 */
289RTDECL(int) RTDbgAsModuleByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTDBGMOD phMod, PRTUINTPTR pAddr, PRTDBGSEGIDX piSeg);
290
291/**
292 * Queries mapping module information by name.
293 *
294 * @returns IPRT status code.
295 * @retval VERR_NOT_FOUND if no mapping was found at the specified address.
296 * @retval VERR_OUT_OF_RANGE if the name index was out of range.
297 *
298 * @param hDbgAs The address space handle.
299 * @param pszName The module name.
300 * @param iName There can be more than one module by the same name
301 * in an address space. This argument indicates which
302 * is ment. (0 based)
303 * @param phMod Where to the return the retained module handle.
304 */
305RTDECL(int) RTDbgAsModuleByName(RTDBGAS hDbgAs, const char *pszName, uint32_t iName, PRTDBGMOD phMod);
306
307/**
308 * Adds a symbol to a module in the address space.
309 *
310 * @returns IPRT status code. See RTDbgModSymbolAdd for more specific ones.
311 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
312 * @retval VERR_NOT_FOUND if no module was found at the specified address.
313 *
314 * @param hDbgAs The address space handle.
315 * @param pszSymbol The symbol name.
316 * @param Addr The address of the symbol.
317 * @param cb The size of the symbol.
318 */
319RTDECL(int) RTDbgAsSymbolAdd(RTDBGAS hDbgAs, const char *pszSymbol, RTUINTPTR Addr, uint32_t cb);
320
321/**
322 * Query a symbol by address.
323 *
324 * @returns IPRT status code. See RTDbgModSymbolAddr for more specific ones.
325 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
326 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
327 *
328 * @param hDbgAs The address space handle.
329 * @param Addr The address which closest symbol is requested.
330 * @param poffDisp Where to return the distance between the symbol
331 * and address. Optional.
332 * @param pSymbol Where to return the symbol info.
333 */
334RTDECL(int) RTDbgAsSymbolByAddr(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol);
335
336/**
337 * Query a symbol by address.
338 *
339 * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
340 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
341 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
342 *
343 * @param hDbgAs The address space handle.
344 * @param Addr The address which closest symbol is requested.
345 * @param poffDisp Where to return the distance between the symbol
346 * and address. Optional.
347 * @param ppSymbol Where to return the pointer to the allocated
348 * symbol info. Always set. Free with RTDbgSymbolFree.
349 */
350RTDECL(int) RTDbgAsSymbolByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymbol);
351
352/**
353 * Query a symbol by name.
354 *
355 * @returns IPRT status code.
356 * @retval VERR_SYMBOL_NOT_FOUND if not found.
357 *
358 * @param hDbgAs The address space handle.
359 * @param pszSymbol The symbol name.
360 * @param pSymbol Where to return the symbol info.
361 */
362RTDECL(int) RTDbgAsSymbolByName(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol);
363
364/**
365 * Query a symbol by name.
366 *
367 * @returns IPRT status code.
368 * @retval VERR_SYMBOL_NOT_FOUND if not found.
369 *
370 * @param hDbgAs The address space handle.
371 * @param pszSymbol The symbol name.
372 * @param ppSymbol Where to return the pointer to the allocated
373 * symbol info. Always set. Free with RTDbgSymbolFree.
374 */
375RTDECL(int) RTDbgAsSymbolByNameA(RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol);
376
377/**
378 * Query a line number by address.
379 *
380 * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
381 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
382 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
383 *
384 * @param hDbgAs The address space handle.
385 * @param Addr The address which closest symbol is requested.
386 * @param poffDisp Where to return the distance between the line
387 * number and address.
388 * @param pLine Where to return the line number information.
389 */
390RTDECL(int) RTDbgAs(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE pLine);
391
392/**
393 * Query a line number by address.
394 *
395 * @returns IPRT status code. See RTDbgModSymbolAddrA for more specific ones.
396 * @retval VERR_INVALID_HANDLE if hDbgAs is invalid.
397 * @retval VERR_NOT_FOUND if the address couldn't be mapped to a module.
398 *
399 * @param hDbgAs The address space handle.
400 * @param Addr The address which closest symbol is requested.
401 * @param poffDisp Where to return the distance between the line
402 * number and address.
403 * @param ppLine Where to return the pointer to the allocated line
404 * number info. Always set. Free with RTDbgLineFree.
405 */
406RTDECL(int) RTDbgAsLineByAddrA(RTDBGAS hDbgAs, RTUINTPTR Addr, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
407
408/** @todo Missing some bits here. */
409
410/** @} */
411
412
413/** @defgroup grp_rt_dbgmod RTDbgMod - Debug Module Interpreter
414 * @{
415 */
416RTDECL(int) RTDbgModCreate(PRTDBGMOD phDbgMod, const char *pszName, const char *pszImgFile, const char *pszDbgFile);
417RTDECL(int) RTDbgModDestroy(RTDBGMOD hDbgMod);
418RTDECL(uint32_t) RTDbgModRetain(RTDBGMOD hDbgMod);
419RTDECL(uint32_t) RTDbgModRelease(RTDBGMOD hDbgMod);
420RTDECL(const char *) RTDbgModName(RTDBGMOD hDbgMod);
421RTDECL(RTUINTPTR) RTDbgModImageSize(RTDBGMOD hDbgMod);
422RTDECL(RTUINTPTR) RTDbgModSegmentSize(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg);
423RTDECL(RTDBGSEGIDX) RTDbgModSegmentCount(RTDBGMOD hDbgMod);
424
425RTDECL(int) RTDbgModSymbolAdd(RTDBGMOD hDbgMod, const char *pszSymbol, RTDBGSEGIDX iSeg, RTUINTPTR off, uint32_t cb);
426RTDECL(uint32_t) RTDbgModSymbolCount(RTDBGMOD hDbgMod);
427RTDECL(int) RTDbgModSymbolByIndex(RTDBGMOD hDbgMod, uint32_t iSymbol, PRTDBGSYMBOL pSymbol);
428RTDECL(int) RTDbgModSymbolByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL pSymbol);
429RTDECL(int) RTDbgModSymbolByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGSYMBOL *ppSymbol);
430RTDECL(int) RTDbgModSymbolByName(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL pSymbol);
431RTDECL(int) RTDbgModSymbolByNameA(RTDBGMOD hDbgMod, const char *pszSymbol, PRTDBGSYMBOL *ppSymbol);
432
433RTDECL(int) RTDbgModLineByAddr(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE pLine);
434RTDECL(int) RTDbgModLineByAddrA(RTDBGMOD hDbgMod, RTDBGSEGIDX iSeg, RTUINTPTR off, PRTINTPTR poffDisp, PRTDBGLINE *ppLine);
435/** @} */
436
437/** @} */
438
439__END_DECLS
440
441#endif
442
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette