VirtualBox

source: vbox/trunk/src/VBox/VMM/VMMR3/DBGFModule.cpp

Last change on this file was 106061, checked in by vboxsync, 3 months ago

Copyright year updates by scm.

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