VirtualBox

source: vbox/trunk/src/VBox/VMM/DBGFModule.cpp@ 30656

Last change on this file since 30656 was 28800, checked in by vboxsync, 15 years ago

Automated rebranding to Oracle copyright/license strings via filemuncher

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 10.7 KB
Line 
1/* $Id: DBGFModule.cpp 28800 2010-04-27 08:22:32Z vboxsync $ */
2/** @file
3 * DBGF - Debugger Facility, Module & Segment Management.
4 */
5
6/*
7 * Copyright (C) 2008 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
18
19/** @page pg_dbgf_module DBGFModule - Module & Segment Management
20 *
21 * A module is our representation of an executable binary. It's main purpose
22 * is to provide segments that can be mapped into address spaces and thereby
23 * provide debug info for those parts for the guest code or data.
24 *
25 * This module will not deal directly with debug info, it will only serve
26 * as an interface between the debugger / symbol lookup and the debug info
27 * readers.
28 *
29 * An executable binary doesn't need to have a file, or that is, we don't
30 * need the file to create a module for it. There will be interfaces for
31 * ROMs to register themselves so we can get to their symbols, and there
32 * will be interfaces for the guest OS plugins (@see pg_dbgf_os) to
33 * register kernel, drivers and other global modules.
34 */
35
36#if 0
37#include <VBox/dbgf.h>
38
39
40/** Special segment number that indicates that the offset is a relative
41 * virtual address (RVA). I.e. an offset from the start of the module. */
42#define DBGF_SEG_RVA UINT32_C(0xfffffff0)
43
44/** @defgroup grp_dbgf_dbginfo Debug Info Types
45 * @{ */
46/** Other format. */
47#define DBGF_DBGINFO_OTHER RT_BIT_32(0)
48/** Stabs. */
49#define DBGF_DBGINFO_STABS RT_BIT_32(1)
50/** Debug With Arbitrary Record Format (DWARF). */
51#define DBGF_DBGINFO_DWARF RT_BIT_32(2)
52/** Microsoft Codeview debug info. */
53#define DBGF_DBGINFO_CODEVIEW RT_BIT_32(3)
54/** Watcom debug info. */
55#define DBGF_DBGINFO_WATCOM RT_BIT_32(4)
56/** IBM High Level Language debug info. */
57#define DBGF_DBGINFO_HLL RT_BIT_32(5)
58/** Old OS/2 and Windows symbol file. */
59#define DBGF_DBGINFO_SYM RT_BIT_32(6)
60/** Map file. */
61#define DBGF_DBGINFO_MAP RT_BIT_32(7)
62/** @} */
63
64/** @defgroup grp_dbgf_exeimg Executable Image Types
65 * @{ */
66/** Some other format. */
67#define DBGF_EXEIMG_OTHER RT_BIT_32(0)
68/** Portable Executable. */
69#define DBGF_EXEIMG_PE RT_BIT_32(1)
70/** Linear eXecutable. */
71#define DBGF_EXEIMG_LX RT_BIT_32(2)
72/** Linear Executable. */
73#define DBGF_EXEIMG_LE RT_BIT_32(3)
74/** New Executable. */
75#define DBGF_EXEIMG_NE RT_BIT_32(4)
76/** DOS Executable (Mark Zbikowski). */
77#define DBGF_EXEIMG_MZ RT_BIT_32(5)
78/** COM Executable. */
79#define DBGF_EXEIMG_COM RT_BIT_32(6)
80/** a.out Executable. */
81#define DBGF_EXEIMG_AOUT RT_BIT_32(7)
82/** Executable and Linkable Format. */
83#define DBGF_EXEIMG_ELF RT_BIT_32(8)
84/** Mach-O Executable (including FAT ones). */
85#define DBGF_EXEIMG_MACHO RT_BIT_32(9)
86/** @} */
87
88/** Pointer to a module. */
89typedef struct DBGFMOD *PDBGFMOD;
90
91
92/**
93 * Virtual method table for executable image interpreters.
94 */
95typedef struct DBGFMODVTIMG
96{
97 /** Magic number (DBGFMODVTIMG_MAGIC). */
98 uint32_t u32Magic;
99 /** Mask of supported debug info types, see grp_dbgf_exeimg.
100 * Used to speed up the search for a suitable interpreter. */
101 uint32_t fSupports;
102 /** The name of the interpreter. */
103 const char *pszName;
104
105 /**
106 * Try open the image.
107 *
108 * This combines probing and opening.
109 *
110 * @returns VBox status code. No informational returns defined.
111 *
112 * @param pMod Pointer to the module that is being opened.
113 *
114 * The DBGFMOD::pszDbgFile member will point to
115 * the filename of any debug info we're aware of
116 * on input. Also, or alternatively, it is expected
117 * that the interpreter will look for debug info in
118 * the executable image file when present and that it
119 * may ask the image interpreter for this when it's
120 * around.
121 *
122 * Upon successful return the method is expected to
123 * initialize pDbgOps and pvDbgPriv.
124 */
125 DECLCALLBACKMEMBER(int, pfnTryOpen)(PDBGFMOD pMod);
126
127 /**
128 * Close the interpreter, freeing all associated resources.
129 *
130 * The caller sets the pDbgOps and pvDbgPriv DBGFMOD members
131 * to NULL upon return.
132 *
133 * @param pMod Pointer to the module structure.
134 */
135 DECLCALLBACKMEMBER(int, pfnClose)(PDBGFMOD pMod);
136
137} DBGFMODVTIMG
138
139/**
140 * Virtual method table for debug info interpreters.
141 */
142typedef struct DBGFMODVTDBG
143{
144 /** Magic number (DBGFMODVTDBG_MAGIC). */
145 uint32_t u32Magic;
146 /** Mask of supported debug info types, see grp_dbgf_dbginfo.
147 * Used to speed up the search for a suitable interpreter. */
148 uint32_t fSupports;
149 /** The name of the interpreter. */
150 const char *pszName;
151
152 /**
153 * Try open the image.
154 *
155 * This combines probing and opening.
156 *
157 * @returns VBox status code. No informational returns defined.
158 *
159 * @param pMod Pointer to the module that is being opened.
160 *
161 * The DBGFMOD::pszDbgFile member will point to
162 * the filename of any debug info we're aware of
163 * on input. Also, or alternatively, it is expected
164 * that the interpreter will look for debug info in
165 * the executable image file when present and that it
166 * may ask the image interpreter for this when it's
167 * around.
168 *
169 * Upon successful return the method is expected to
170 * initialize pDbgOps and pvDbgPriv.
171 */
172 DECLCALLBACKMEMBER(int, pfnTryOpen)(PDBGFMOD pMod);
173
174 /**
175 * Close the interpreter, freeing all associated resources.
176 *
177 * The caller sets the pDbgOps and pvDbgPriv DBGFMOD members
178 * to NULL upon return.
179 *
180 * @param pMod Pointer to the module structure.
181 */
182 DECLCALLBACKMEMBER(int, pfnClose)(PDBGFMOD pMod);
183
184 /**
185 * Queries symbol information by symbol name.
186 *
187 * @returns VBox status code.
188 * @retval VINF_SUCCESS on success, no informational status code.
189 * @retval VERR_DBGF_NO_SYMBOLS if there aren't any symbols.
190 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
191 *
192 * @param pMod Pointer to the module structure.
193 * @param pszSymbol The symbol name.
194 * @para pSymbol Where to store the symbol information.
195 */
196 DECLCALLBACKMEMBER(int, pfnSymbolByName)(PDBGFMOD pMod, const char *pszSymbol, PDBGFSYMBOL pSymbol);
197
198 /**
199 * Queries symbol information by address.
200 *
201 * The returned symbol is what the debug info interpreter consideres the symbol
202 * most applicable to the specified address. This usually means a symbol with an
203 * address equal or lower than the requested.
204 *
205 * @returns VBox status code.
206 * @retval VINF_SUCCESS on success, no informational status code.
207 * @retval VERR_DBGF_NO_SYMBOLS if there aren't any symbols.
208 * @retval VERR_SYMBOL_NOT_FOUND if no suitable symbol was found.
209 *
210 * @param pMod Pointer to the module structure.
211 * @param iSeg The segment number (0-based). DBGF_SEG_RVA can be used.
212 * @param off The offset into the segment.
213 * @param poffDisp Where to store the distance between the specified address
214 * and the returned symbol. Optional.
215 * @param pSymbol Where to store the symbol information.
216 */
217 DECLCALLBACKMEMBER(int, pfnSymbolByAddr)(PDBGFMOD pMod, uint32_t iSeg, RTGCUINTPTR off, PRTGCINTPTR poffDisp, PDBGFSYMBOL pSymbol);
218
219 /**
220 * Queries line number information by address.
221 *
222 * @returns VBox status code.
223 * @retval VINF_SUCCESS on success, no informational status code.
224 * @retval VERR_DBGF_NO_LINE_NUMBERS if there aren't any line numbers.
225 * @retval VERR_DBGF_LINE_NOT_FOUND if no suitable line number was found.
226 *
227 * @param pMod Pointer to the module structure.
228 * @param iSeg The segment number (0-based). DBGF_SEG_RVA can be used.
229 * @param off The offset into the segment.
230 * @param poffDisp Where to store the distance between the specified address
231 * and the returned line number. Optional.
232 * @param pLine Where to store the information about the closest line number.
233 */
234 DECLCALLBACKMEMBER(int, pfnLineByAddr)(PDBGFMOD pMod, uint32_t iSeg, RTGCUINTPTR off, PRTGCINTPTR poffDisp, PDBGFLINE pLine);
235
236 /**
237 * Adds a symbol to the module (optional).
238 *
239 * This method is used to implement DBGFR3SymbolAdd.
240 *
241 * @returns VBox status code.
242 * @retval VERR_NOT_SUPPORTED if the interpreter doesn't support this feature.
243 *
244 * @param pMod Pointer to the module structure.
245 * @param pszSymbol The symbol name.
246 * @param iSeg The segment number (0-based). DBGF_SEG_RVA can be used.
247 * @param off The offset into the segment.
248 * @param cbSymbol The area covered by the symbol. 0 is fine.
249 */
250 DECLCALLBACKMEMBER(int, pfnSymbolAdd)(PDBGFMOD pMod, const char *pszSymbol, uint32_t iSeg, RTGCUINTPTR off, RTUINT cbSymbol);
251
252 /** For catching initialization errors (DBGFMODVTDBG_MAGIC). */
253 uint32_t u32EndMagic;
254} DBGFMODVTDBG;
255
256#define DBGFMODVTDBG_MAGIC 123
257
258/**
259 * Module.
260 */
261typedef struct DBGFMOD
262{
263 /** Magic value (DBGFMOD_MAGIC). */
264 uint32_t u32Magic;
265 /** The number of address spaces this module is currently linked into.
266 * This is used to perform automatic cleanup and sharing. */
267 uint32_t cLinks;
268 /** The module name (short). */
269 const char *pszName;
270 /** The module filename. Can be NULL. */
271 const char *pszImgFile;
272 /** The debug info file (if external). Can be NULL. */
273 const char *pszDbgFile;
274
275 /** The method table for the executable image interpreter. */
276 PCDBGFMODVTIMG pImgVt;
277 /** Pointer to the private data of the executable image interpreter. */
278 void *pvImgPriv;
279
280 /** The method table for the debug info interpreter. */
281 PCDBGFMODVTDBG pDbgVt;
282 /** Pointer to the private data of the debug info interpreter. */
283 void *pvDbgPriv;
284
285} DBGFMOD;
286
287#define DBGFMOD_MAGIC 0x12345678
288
289#endif
290
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