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