← Back to branch summary

~ubuntu-branches/ubuntu/trusty/virtualbox-lts-xenial/trusty-updates

« back to all changes in this revision

Viewing changes to src/VBox/VMM/VMMR3/DBGFModule.cpp

  • Committer: Package Import Robot
  • Author(s): Gianfranco Costamagna
  • Date: 2016-02-23 14:28:26 UTC
  • Revision ID: package-import@ubuntu.com-20160223142826-bdu69el2z6wa2a44
Tags: upstream-4.3.36-dfsg
Import upstream version 4.3.36-dfsg

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/VBox/VMM/VMMR3/DBGFModule.cpp
 
1
/* $Id: DBGFModule.cpp $ */
 
2
/** @file
 
3
 * DBGF - Debugger Facility, Module & Segment Management.
 
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
 
 
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/vmm/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. */
 
89
typedef struct DBGFMOD *PDBGFMOD;
 
90
 
 
91
 
 
92
/**
 
93
 * Virtual method table for executable image interpreters.
 
94
 */
 
95
typedef 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
 */
 
142
typedef 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 considers 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
 */
 
261
typedef 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