VirtualBox

source: vbox/trunk/include/VBox/dbgf.h@ 19239

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

DBGFAddr: Three new APIs for address conversion that takes threading into account.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 33.5 KB
Line 
1/** @file
2 * DBGF - Debugger Facility.
3 */
4
5/*
6 * Copyright (C) 2006-2007 Sun Microsystems, Inc.
7 *
8 * This file is part of VirtualBox Open Source Edition (OSE), as
9 * available from http://www.virtualbox.org. This file is free software;
10 * you can redistribute it and/or modify it under the terms of the GNU
11 * General Public License (GPL) as published by the Free Software
12 * Foundation, in version 2 as it comes in the "COPYING" file of the
13 * VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14 * hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15 *
16 * The contents of this file may alternatively be used under the terms
17 * of the Common Development and Distribution License Version 1.0
18 * (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19 * VirtualBox OSE distribution, in which case the provisions of the
20 * CDDL are applicable instead of those of the GPL.
21 *
22 * You may elect to license modified versions of this file under the
23 * terms and conditions of either the GPL or the CDDL or both.
24 *
25 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa
26 * Clara, CA 95054 USA or visit http://www.sun.com if you need
27 * additional information or have any questions.
28 */
29
30#ifndef ___VBox_dbgf_h
31#define ___VBox_dbgf_h
32
33#include <VBox/cdefs.h>
34#include <VBox/types.h>
35#include <VBox/vmm.h>
36#include <VBox/log.h> /* LOG_ENABLED */
37
38#include <iprt/stdarg.h>
39
40__BEGIN_DECLS
41
42
43/** @defgroup grp_dbgf The Debugger Facility API
44 * @{
45 */
46
47#ifdef IN_RC
48/** @addgroup grp_dbgf_gc The GC DBGF API
49 * @ingroup grp_dbgf
50 * @{
51 */
52VMMRCDECL(int) DBGFGCTrap01Handler(PVM pVM, PCPUMCTXCORE pRegFrame, RTGCUINTREG uDr6);
53VMMRCDECL(int) DBGFGCTrap03Handler(PVM pVM, PCPUMCTXCORE pRegFrame);
54/** @} */
55#endif
56
57#ifdef IN_RING0
58/** @addgroup grp_dbgf_gc The R0 DBGF API
59 * @ingroup grp_dbgf
60 * @{
61 */
62VMMR0DECL(int) DBGFR0Trap01Handler(PVM pVM, PCPUMCTXCORE pRegFrame, RTGCUINTREG uDr6);
63VMMR0DECL(int) DBGFR0Trap03Handler(PVM pVM, PCPUMCTXCORE pRegFrame);
64/** @} */
65#endif
66
67
68
69/**
70 * Mixed address.
71 */
72typedef struct DBGFADDRESS
73{
74 /** The flat address. */
75 RTGCUINTPTR FlatPtr;
76 /** The selector offset address. */
77 RTGCUINTPTR off;
78 /** The selector. DBGF_SEL_FLAT is a legal value. */
79 RTSEL Sel;
80 /** Flags describing further details about the address. */
81 uint16_t fFlags;
82} DBGFADDRESS;
83/** Pointer to a mixed address. */
84typedef DBGFADDRESS *PDBGFADDRESS;
85/** Pointer to a const mixed address. */
86typedef const DBGFADDRESS *PCDBGFADDRESS;
87
88/** @name DBGFADDRESS Flags.
89 * @{ */
90/** A 16:16 far address. */
91#define DBGFADDRESS_FLAGS_FAR16 0
92/** A 16:32 far address. */
93#define DBGFADDRESS_FLAGS_FAR32 1
94/** A 16:64 far address. */
95#define DBGFADDRESS_FLAGS_FAR64 2
96/** A flat address. */
97#define DBGFADDRESS_FLAGS_FLAT 3
98/** A physical address. */
99#define DBGFADDRESS_FLAGS_PHYS 4
100/** The address type mask. */
101#define DBGFADDRESS_FLAGS_TYPE_MASK 7
102
103/** Set if the address is valid. */
104#define DBGFADDRESS_FLAGS_VALID RT_BIT(3)
105
106/** The address is within the hypervisor memoary area (HMA).
107 * If not set, the address can be assumed to be a guest address. */
108#define DBGFADDRESS_FLAGS_HMA RT_BIT(4)
109
110/** Checks if the mixed address is flat or not. */
111#define DBGFADDRESS_IS_FLAT(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FLAT )
112/** Checks if the mixed address is flat or not. */
113#define DBGFADDRESS_IS_PHYS(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_PHYS )
114/** Checks if the mixed address is far 16:16 or not. */
115#define DBGFADDRESS_IS_FAR16(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR16 )
116/** Checks if the mixed address is far 16:32 or not. */
117#define DBGFADDRESS_IS_FAR32(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR32 )
118/** Checks if the mixed address is far 16:64 or not. */
119#define DBGFADDRESS_IS_FAR64(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR64 )
120/** Checks if the mixed address is valid. */
121#define DBGFADDRESS_IS_VALID(pAddress) ( !!((pAddress)->fFlags & DBGFADDRESS_FLAGS_VALID) )
122/** Checks if the address is flagged as within the HMA. */
123#define DBGFADDRESS_IS_HMA(pAddress) ( !!((pAddress)->fFlags & DBGFADDRESS_FLAGS_HMA) )
124/** @} */
125
126VMMR3DECL(int) DBGFR3AddrFromSelOff(PVM pVM, PDBGFADDRESS pAddress, RTSEL Sel, RTUINTPTR off);
127VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromFlat(PVM pVM, PDBGFADDRESS pAddress, RTGCUINTPTR FlatPtr);
128VMMR3DECL(void) DBGFR3AddrFromPhys(PVM pVM, PDBGFADDRESS pAddress, RTGCPHYS PhysAddr);
129VMMR3DECL(bool) DBGFR3AddrIsValid(PVM pVM, PCDBGFADDRESS pAddress);
130VMMR3DECL(int) DBGFR3AddrToPhys(PVMCPU pVCpu, PDBGFADDRESS pAddress, PRTGCPHYS pGCPhys);
131VMMR3DECL(int) DBGFR3AddrToHostPhys(PVMCPU pVCpu, PDBGFADDRESS pAddress, PRTHCPHYS pHCPhys);
132VMMR3DECL(int) DBGFR3AddrToVolatileR3Ptr(PVMCPU pVCpu, PDBGFADDRESS pAddress, bool fReadOnly, void **ppvR3Ptr);
133
134
135
136
137/**
138 * VMM Debug Event Type.
139 */
140typedef enum DBGFEVENTTYPE
141{
142 /** Halt completed.
143 * This notifies that a halt command have been successfully completed.
144 */
145 DBGFEVENT_HALT_DONE = 0,
146 /** Detach completed.
147 * This notifies that the detach command have been successfully completed.
148 */
149 DBGFEVENT_DETACH_DONE,
150 /** The command from the debugger is not recognized.
151 * This means internal error or half implemented features.
152 */
153 DBGFEVENT_INVALID_COMMAND,
154
155
156 /** Fatal error.
157 * This notifies a fatal error in the VMM and that the debugger get's a
158 * chance to first hand information about the the problem.
159 */
160 DBGFEVENT_FATAL_ERROR = 100,
161 /** Breakpoint Hit.
162 * This notifies that a breakpoint installed by the debugger was hit. The
163 * identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
164 */
165 DBGFEVENT_BREAKPOINT,
166 /** Breakpoint Hit in the Hypervisor.
167 * This notifies that a breakpoint installed by the debugger was hit. The
168 * identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
169 */
170 DBGFEVENT_BREAKPOINT_HYPER,
171 /** Assertion in the Hypervisor (breakpoint instruction).
172 * This notifies that a breakpoint instruction was hit in the hypervisor context.
173 */
174 DBGFEVENT_ASSERTION_HYPER,
175 /** Single Stepped.
176 * This notifies that a single step operation was completed.
177 */
178 DBGFEVENT_STEPPED,
179 /** Single Stepped.
180 * This notifies that a hypervisor single step operation was completed.
181 */
182 DBGFEVENT_STEPPED_HYPER,
183 /** The developer have used the DBGFSTOP macro or the PDMDeviceDBGFSTOP function
184 * to bring up the debugger at a specific place.
185 */
186 DBGFEVENT_DEV_STOP,
187 /** The VM is terminating.
188 * When this notification is received, the debugger thread should detach ASAP.
189 */
190 DBGFEVENT_TERMINATING,
191
192 /** The usual 32-bit hack. */
193 DBGFEVENT_32BIT_HACK = 0x7fffffff
194} DBGFEVENTTYPE;
195
196
197/**
198 * The context of an event.
199 */
200typedef enum DBGFEVENTCTX
201{
202 /** The usual invalid entry. */
203 DBGFEVENTCTX_INVALID = 0,
204 /** Raw mode. */
205 DBGFEVENTCTX_RAW,
206 /** Recompiled mode. */
207 DBGFEVENTCTX_REM,
208 /** VMX / AVT mode. */
209 DBGFEVENTCTX_HWACCL,
210 /** Hypervisor context. */
211 DBGFEVENTCTX_HYPER,
212 /** Other mode */
213 DBGFEVENTCTX_OTHER,
214
215 /** The usual 32-bit hack */
216 DBGFEVENTCTX_32BIT_HACK = 0x7fffffff
217} DBGFEVENTCTX;
218
219/**
220 * VMM Debug Event.
221 */
222typedef struct DBGFEVENT
223{
224 /** Type. */
225 DBGFEVENTTYPE enmType;
226 /** Context */
227 DBGFEVENTCTX enmCtx;
228 /** Type specific data. */
229 union
230 {
231 /** Fatal error details. */
232 struct
233 {
234 /** The GC return code. */
235 int rc;
236 } FatalError;
237
238 /** Source location. */
239 struct
240 {
241 /** File name. */
242 R3PTRTYPE(const char *) pszFile;
243 /** Function name. */
244 R3PTRTYPE(const char *) pszFunction;
245 /** Message. */
246 R3PTRTYPE(const char *) pszMessage;
247 /** Line number. */
248 unsigned uLine;
249 } Src;
250
251 /** Assertion messages. */
252 struct
253 {
254 /** The first message. */
255 R3PTRTYPE(const char *) pszMsg1;
256 /** The second message. */
257 R3PTRTYPE(const char *) pszMsg2;
258 } Assert;
259
260 /** Breakpoint. */
261 struct DBGFEVENTBP
262 {
263 /** The identifier of the breakpoint which was hit. */
264 RTUINT iBp;
265 } Bp;
266 /** Padding for ensuring that the structure is 8 byte aligned. */
267 uint64_t au64Padding[4];
268 } u;
269} DBGFEVENT;
270/** Pointer to VMM Debug Event. */
271typedef DBGFEVENT *PDBGFEVENT;
272/** Pointer to const VMM Debug Event. */
273typedef const DBGFEVENT *PCDBGFEVENT;
274
275
276/** @def DBGFSTOP
277 * Stops the debugger raising a DBGFEVENT_DEVELOPER_STOP event.
278 *
279 * @returns VBox status code which must be propagated up to EM if not VINF_SUCCESS.
280 * @param pVM VM Handle.
281 */
282#ifdef VBOX_STRICT
283# define DBGFSTOP(pVM) DBGFR3EventSrc(pVM, DBGFEVENT_DEV_STOP, __FILE__, __LINE__, __PRETTY_FUNCTION__, NULL)
284#else
285# define DBGFSTOP(pVM) VINF_SUCCESS
286#endif
287
288VMMR3DECL(int) DBGFR3Init(PVM pVM);
289VMMR3DECL(int) DBGFR3Term(PVM pVM);
290VMMR3DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta);
291VMMR3DECL(int) DBGFR3VMMForcedAction(PVM pVM);
292VMMR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent);
293VMMR3DECL(int) DBGFR3EventSrc(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine, const char *pszFunction, const char *pszFormat, ...);
294VMMR3DECL(int) DBGFR3EventSrcV(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine, const char *pszFunction, const char *pszFormat, va_list args);
295VMMR3DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszMsg1, const char *pszMsg2);
296VMMR3DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent);
297VMMR3DECL(int) DBGFR3Attach(PVM pVM);
298VMMR3DECL(int) DBGFR3Detach(PVM pVM);
299VMMR3DECL(int) DBGFR3EventWait(PVM pVM, unsigned cMillies, PCDBGFEVENT *ppEvent);
300VMMR3DECL(int) DBGFR3Halt(PVM pVM);
301VMMR3DECL(bool) DBGFR3IsHalted(PVM pVM);
302VMMR3DECL(bool) DBGFR3CanWait(PVM pVM);
303VMMR3DECL(int) DBGFR3Resume(PVM pVM);
304VMMR3DECL(int) DBGFR3Step(PVM pVM);
305VMMR3DECL(int) DBGFR3PrgStep(PVM pVM);
306
307
308/** Breakpoint type. */
309typedef enum DBGFBPTYPE
310{
311 /** Free breakpoint entry. */
312 DBGFBPTYPE_FREE = 0,
313 /** Debug register. */
314 DBGFBPTYPE_REG,
315 /** INT 3 instruction. */
316 DBGFBPTYPE_INT3,
317 /** Recompiler. */
318 DBGFBPTYPE_REM,
319 /** ensure 32-bit size. */
320 DBGFBPTYPE_32BIT_HACK = 0x7fffffff
321} DBGFBPTYPE;
322
323
324/**
325 * A Breakpoint.
326 */
327typedef struct DBGFBP
328{
329 /** The number of breakpoint hits. */
330 uint64_t cHits;
331 /** The hit number which starts to trigger the breakpoint. */
332 uint64_t iHitTrigger;
333 /** The hit number which stops triggering the breakpoint (disables it).
334 * Use ~(uint64_t)0 if it should never stop. */
335 uint64_t iHitDisable;
336 /** The Flat GC address of the breakpoint.
337 * (PC register value if REM type?) */
338 RTGCUINTPTR GCPtr;
339 /** The breakpoint id. */
340 RTUINT iBp;
341 /** The breakpoint status - enabled or disabled. */
342 bool fEnabled;
343
344 /** The breakpoint type. */
345 DBGFBPTYPE enmType;
346
347#if GC_ARCH_BITS == 64
348 uint32_t u32Padding;
349#endif
350
351 /** Union of type specific data. */
352 union
353 {
354 /** Debug register data. */
355 struct DBGFBPREG
356 {
357 /** The debug register number. */
358 uint8_t iReg;
359 /** The access type (one of the X86_DR7_RW_* value). */
360 uint8_t fType;
361 /** The access size. */
362 uint8_t cb;
363 } Reg;
364 /** Recompiler breakpoint data. */
365 struct DBGFBPINT3
366 {
367 /** The byte value we replaced by the INT 3 instruction. */
368 uint8_t bOrg;
369 } Int3;
370
371 /** Recompiler breakpoint data. */
372 struct DBGFBPREM
373 {
374 /** nothing yet */
375 uint8_t fDummy;
376 } Rem;
377 /** Paddind to ensure that the size is identical on win32 and linux. */
378 uint64_t u64Padding;
379 } u;
380} DBGFBP;
381
382/** Pointer to a breakpoint. */
383typedef DBGFBP *PDBGFBP;
384/** Pointer to a const breakpoint. */
385typedef const DBGFBP *PCDBGFBP;
386
387
388VMMR3DECL(int) DBGFR3BpSet(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, PRTUINT piBp);
389VMMR3DECL(int) DBGFR3BpSetReg(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable,
390 uint8_t fType, uint8_t cb, PRTUINT piBp);
391VMMR3DECL(int) DBGFR3BpSetREM(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, PRTUINT piBp);
392VMMR3DECL(int) DBGFR3BpClear(PVM pVM, RTUINT iBp);
393VMMR3DECL(int) DBGFR3BpEnable(PVM pVM, RTUINT iBp);
394VMMR3DECL(int) DBGFR3BpDisable(PVM pVM, RTUINT iBp);
395
396/**
397 * Breakpoint enumeration callback function.
398 *
399 * @returns VBox status code. Any failure will stop the enumeration.
400 * @param pVM The VM handle.
401 * @param pvUser The user argument.
402 * @param pBp Pointer to the breakpoint information. (readonly)
403 */
404typedef DECLCALLBACK(int) FNDBGFBPENUM(PVM pVM, void *pvUser, PCDBGFBP pBp);
405/** Pointer to a breakpoint enumeration callback function. */
406typedef FNDBGFBPENUM *PFNDBGFBPENUM;
407
408VMMR3DECL(int) DBGFR3BpEnum(PVM pVM, PFNDBGFBPENUM pfnCallback, void *pvUser);
409VMMDECL(RTGCUINTREG) DBGFBpGetDR7(PVM pVM);
410VMMDECL(RTGCUINTREG) DBGFBpGetDR0(PVM pVM);
411VMMDECL(RTGCUINTREG) DBGFBpGetDR1(PVM pVM);
412VMMDECL(RTGCUINTREG) DBGFBpGetDR2(PVM pVM);
413VMMDECL(RTGCUINTREG) DBGFBpGetDR3(PVM pVM);
414VMMDECL(bool) DBGFIsStepping(PVM pVM);
415
416
417
418
419/** Pointer to a info helper callback structure. */
420typedef struct DBGFINFOHLP *PDBGFINFOHLP;
421/** Pointer to a const info helper callback structure. */
422typedef const struct DBGFINFOHLP *PCDBGFINFOHLP;
423
424/**
425 * Info helper callback structure.
426 */
427typedef struct DBGFINFOHLP
428{
429 /**
430 * Print formatted string.
431 *
432 * @param pHlp Pointer to this structure.
433 * @param pszFormat The format string.
434 * @param ... Arguments.
435 */
436 DECLCALLBACKMEMBER(void, pfnPrintf)(PCDBGFINFOHLP pHlp, const char *pszFormat, ...);
437
438 /**
439 * Print formatted string.
440 *
441 * @param pHlp Pointer to this structure.
442 * @param pszFormat The format string.
443 * @param args Argument list.
444 */
445 DECLCALLBACKMEMBER(void, pfnPrintfV)(PCDBGFINFOHLP pHlp, const char *pszFormat, va_list args);
446} DBGFINFOHLP;
447
448
449/**
450 * Info handler, device version.
451 *
452 * @param pDevIns Device instance which registered the info.
453 * @param pHlp Callback functions for doing output.
454 * @param pszArgs Argument string. Optional and specific to the handler.
455 */
456typedef DECLCALLBACK(void) FNDBGFHANDLERDEV(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
457/** Pointer to a FNDBGFHANDLERDEV function. */
458typedef FNDBGFHANDLERDEV *PFNDBGFHANDLERDEV;
459
460/**
461 * Info handler, driver version.
462 *
463 * @param pDrvIns Driver instance which registered the info.
464 * @param pHlp Callback functions for doing output.
465 * @param pszArgs Argument string. Optional and specific to the handler.
466 */
467typedef DECLCALLBACK(void) FNDBGFHANDLERDRV(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
468/** Pointer to a FNDBGFHANDLERDRV function. */
469typedef FNDBGFHANDLERDRV *PFNDBGFHANDLERDRV;
470
471/**
472 * Info handler, internal version.
473 *
474 * @param pVM The VM handle.
475 * @param pHlp Callback functions for doing output.
476 * @param pszArgs Argument string. Optional and specific to the handler.
477 */
478typedef DECLCALLBACK(void) FNDBGFHANDLERINT(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs);
479/** Pointer to a FNDBGFHANDLERINT function. */
480typedef FNDBGFHANDLERINT *PFNDBGFHANDLERINT;
481
482/**
483 * Info handler, external version.
484 *
485 * @param pvUser User argument.
486 * @param pHlp Callback functions for doing output.
487 * @param pszArgs Argument string. Optional and specific to the handler.
488 */
489typedef DECLCALLBACK(void) FNDBGFHANDLEREXT(void *pvUser, PCDBGFINFOHLP pHlp, const char *pszArgs);
490/** Pointer to a FNDBGFHANDLEREXT function. */
491typedef FNDBGFHANDLEREXT *PFNDBGFHANDLEREXT;
492
493
494/** @name Flags for the info registration functions.
495 * @{ */
496/** The handler must run on the EMT. */
497#define DBGFINFO_FLAGS_RUN_ON_EMT RT_BIT(0)
498/** @} */
499
500VMMR3DECL(int) DBGFR3InfoRegisterDevice(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler, PPDMDEVINS pDevIns);
501VMMR3DECL(int) DBGFR3InfoRegisterDriver(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDRV pfnHandler, PPDMDRVINS pDrvIns);
502VMMR3DECL(int) DBGFR3InfoRegisterInternal(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERINT pfnHandler);
503VMMR3DECL(int) DBGFR3InfoRegisterInternalEx(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERINT pfnHandler, uint32_t fFlags);
504VMMR3DECL(int) DBGFR3InfoRegisterExternal(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLEREXT pfnHandler, void *pvUser);
505VMMR3DECL(int) DBGFR3InfoDeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName);
506VMMR3DECL(int) DBGFR3InfoDeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName);
507VMMR3DECL(int) DBGFR3InfoDeregisterInternal(PVM pVM, const char *pszName);
508VMMR3DECL(int) DBGFR3InfoDeregisterExternal(PVM pVM, const char *pszName);
509VMMR3DECL(int) DBGFR3Info(PVM pVM, const char *pszName, const char *pszArgs, PCDBGFINFOHLP pHlp);
510
511/** @def DBGFR3InfoLog
512 * Display a piece of info writing to the log if enabled.
513 *
514 * @param pVM VM handle.
515 * @param pszName The identifier of the info to display.
516 * @param pszArgs Arguments to the info handler.
517 */
518#ifdef LOG_ENABLED
519#define DBGFR3InfoLog(pVM, pszName, pszArgs) \
520 do { \
521 if (LogIsEnabled()) \
522 DBGFR3Info(pVM, pszName, pszArgs, NULL); \
523 } while (0)
524#else
525#define DBGFR3InfoLog(pVM, pszName, pszArgs) do { } while (0)
526#endif
527
528/**
529 * Enumeration callback for use with DBGFR3InfoEnum.
530 *
531 * @returns VBox status code.
532 * A status code indicating failure will end the enumeration
533 * and DBGFR3InfoEnum will return with that status code.
534 * @param pVM VM handle.
535 * @param pszName Info identifier name.
536 * @param pszDesc The description.
537 */
538typedef DECLCALLBACK(int) FNDBGFINFOENUM(PVM pVM, const char *pszName, const char *pszDesc, void *pvUser);
539/** Pointer to a FNDBGFINFOENUM function. */
540typedef FNDBGFINFOENUM *PFNDBGFINFOENUM;
541
542VMMR3DECL(int) DBGFR3InfoEnum(PVM pVM, PFNDBGFINFOENUM pfnCallback, void *pvUser);
543VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogHlp(void);
544VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogRelHlp(void);
545
546
547
548VMMR3DECL(int) DBGFR3LogModifyGroups(PVM pVM, const char *pszGroupSettings);
549VMMR3DECL(int) DBGFR3LogModifyFlags(PVM pVM, const char *pszFlagSettings);
550VMMR3DECL(int) DBGFR3LogModifyDestinations(PVM pVM, const char *pszDestSettings);
551
552
553
554/** Max length (including '\\0') of a symbol name. */
555#define DBGF_SYMBOL_NAME_LENGTH 512
556
557/**
558 * Debug symbol.
559 */
560typedef struct DBGFSYMBOL
561{
562 /** Symbol value (address). */
563 RTGCUINTPTR Value;
564 /** Symbol size. */
565 uint32_t cb;
566 /** Symbol Flags. (reserved). */
567 uint32_t fFlags;
568 /** Symbol name. */
569 char szName[DBGF_SYMBOL_NAME_LENGTH];
570} DBGFSYMBOL;
571/** Pointer to debug symbol. */
572typedef DBGFSYMBOL *PDBGFSYMBOL;
573/** Pointer to const debug symbol. */
574typedef const DBGFSYMBOL *PCDBGFSYMBOL;
575
576/**
577 * Debug line number information.
578 */
579typedef struct DBGFLINE
580{
581 /** Address. */
582 RTGCUINTPTR Address;
583 /** Line number. */
584 uint32_t uLineNo;
585 /** Filename. */
586 char szFilename[260];
587} DBGFLINE;
588/** Pointer to debug line number. */
589typedef DBGFLINE *PDBGFLINE;
590/** Pointer to const debug line number. */
591typedef const DBGFLINE *PCDBGFLINE;
592
593VMMR3DECL(int) DBGFR3ModuleLoad(PVM pVM, const char *pszFilename, RTGCUINTPTR AddressDelta, const char *pszName, RTGCUINTPTR ModuleAddress, unsigned cbImage);
594VMMR3DECL(void) DBGFR3ModuleRelocate(PVM pVM, RTGCUINTPTR OldImageBase, RTGCUINTPTR NewImageBase, RTGCUINTPTR cbImage,
595 const char *pszFilename, const char *pszName);
596VMMR3DECL(int) DBGFR3SymbolAdd(PVM pVM, RTGCUINTPTR ModuleAddress, RTGCUINTPTR SymbolAddress, RTUINT cbSymbol, const char *pszSymbol);
597VMMR3DECL(int) DBGFR3SymbolByAddr(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement, PDBGFSYMBOL pSymbol);
598VMMR3DECL(int) DBGFR3SymbolByName(PVM pVM, const char *pszSymbol, PDBGFSYMBOL pSymbol);
599VMMR3DECL(PDBGFSYMBOL) DBGFR3SymbolByAddrAlloc(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement);
600VMMR3DECL(PDBGFSYMBOL) DBGFR3SymbolByNameAlloc(PVM pVM, const char *pszSymbol);
601VMMR3DECL(void) DBGFR3SymbolFree(PDBGFSYMBOL pSymbol);
602VMMR3DECL(int) DBGFR3LineByAddr(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement, PDBGFLINE pLine);
603VMMR3DECL(PDBGFLINE) DBGFR3LineByAddrAlloc(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement);
604VMMR3DECL(void) DBGFR3LineFree(PDBGFLINE pLine);
605
606
607/**
608 * Return type.
609 */
610typedef enum DBGFRETRUNTYPE
611{
612 /** The usual invalid 0 value. */
613 DBGFRETURNTYPE_INVALID = 0,
614 /** Near 16-bit return. */
615 DBGFRETURNTYPE_NEAR16,
616 /** Near 32-bit return. */
617 DBGFRETURNTYPE_NEAR32,
618 /** Near 64-bit return. */
619 DBGFRETURNTYPE_NEAR64,
620 /** Far 16:16 return. */
621 DBGFRETURNTYPE_FAR16,
622 /** Far 16:32 return. */
623 DBGFRETURNTYPE_FAR32,
624 /** Far 16:64 return. */
625 DBGFRETURNTYPE_FAR64,
626 /** 16-bit iret return (e.g. real or 286 protect mode). */
627 DBGFRETURNTYPE_IRET16,
628 /** 32-bit iret return. */
629 DBGFRETURNTYPE_IRET32,
630 /** 32-bit iret return. */
631 DBGFRETURNTYPE_IRET32_PRIV,
632 /** 32-bit iret return to V86 mode. */
633 DBGFRETURNTYPE_IRET32_V86,
634 /** @todo 64-bit iret return. */
635 DBGFRETURNTYPE_IRET64,
636 /** The usual 32-bit blowup. */
637 DBGFRETURNTYPE_32BIT_HACK = 0x7fffffff
638} DBGFRETURNTYPE;
639
640/**
641 * Figures the size of the return state on the stack.
642 *
643 * @returns number of bytes. 0 if invalid parameter.
644 * @param enmRetType The type of return.
645 */
646DECLINLINE(unsigned) DBGFReturnTypeSize(DBGFRETURNTYPE enmRetType)
647{
648 switch (enmRetType)
649 {
650 case DBGFRETURNTYPE_NEAR16: return 2;
651 case DBGFRETURNTYPE_NEAR32: return 4;
652 case DBGFRETURNTYPE_NEAR64: return 8;
653 case DBGFRETURNTYPE_FAR16: return 4;
654 case DBGFRETURNTYPE_FAR32: return 4;
655 case DBGFRETURNTYPE_FAR64: return 8;
656 case DBGFRETURNTYPE_IRET16: return 6;
657 case DBGFRETURNTYPE_IRET32: return 4*3;
658 case DBGFRETURNTYPE_IRET32_PRIV: return 4*5;
659 case DBGFRETURNTYPE_IRET32_V86: return 4*9;
660 case DBGFRETURNTYPE_IRET64:
661 default:
662 return 0;
663 }
664}
665
666
667/** Pointer to stack frame info. */
668typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
669/**
670 * Info about a stack frame.
671 */
672typedef struct DBGFSTACKFRAME
673{
674 /** Frame number. */
675 RTUINT iFrame;
676 /** Frame flags. */
677 RTUINT fFlags;
678 /** The frame address.
679 * The off member is [e|r]bp and the Sel member is ss. */
680 DBGFADDRESS AddrFrame;
681 /** The stack address of the frame.
682 * The off member is [e|r]sp and the Sel member is ss. */
683 DBGFADDRESS AddrStack;
684 /** The program counter (PC) address of the frame.
685 * The off member is [e|r]ip and the Sel member is cs. */
686 DBGFADDRESS AddrPC;
687 /** Pointer to the symbol nearest the program counter (PC). NULL if not found. */
688 PDBGFSYMBOL pSymPC;
689 /** Pointer to the linnumber nearest the program counter (PC). NULL if not found. */
690 PDBGFLINE pLinePC;
691
692 /** The return frame address.
693 * The off member is [e|r]bp and the Sel member is ss. */
694 DBGFADDRESS AddrReturnFrame;
695 /** The return stack address.
696 * The off member is [e|r]sp and the Sel member is ss. */
697 DBGFADDRESS AddrReturnStack;
698 /** The way this frame returns to the next one. */
699 DBGFRETURNTYPE enmReturnType;
700
701 /** The program counter (PC) address which the frame returns to.
702 * The off member is [e|r]ip and the Sel member is cs. */
703 DBGFADDRESS AddrReturnPC;
704 /** Pointer to the symbol nearest the return PC. NULL if not found. */
705 PDBGFSYMBOL pSymReturnPC;
706 /** Pointer to the linnumber nearest the return PC. NULL if not found. */
707 PDBGFLINE pLineReturnPC;
708
709 /** 32-bytes of stack arguments. */
710 union
711 {
712 /** 64-bit view */
713 uint64_t au64[4];
714 /** 32-bit view */
715 uint32_t au32[8];
716 /** 16-bit view */
717 uint16_t au16[16];
718 /** 8-bit view */
719 uint8_t au8[32];
720 } Args;
721
722 /** Pointer to the next frame.
723 * Might not be used in some cases, so consider it internal. */
724 PDBGFSTACKFRAME pNext;
725 /** Pointer to the first frame.
726 * Might not be used in some cases, so consider it internal. */
727 PDBGFSTACKFRAME pFirst;
728} DBGFSTACKFRAME;
729
730/** @name DBGFSTACKFRAME Flags.
731 * @{ */
732/** Set if the content of the frame is filled in by DBGFR3StackWalk() and can be used
733 * to construct the next frame. */
734#define DBGFSTACKFRAME_FLAGS_ALL_VALID RT_BIT(0)
735/** This is the last stack frame we can read.
736 * This flag is not set if the walk stop because of max dept or recursion. */
737#define DBGFSTACKFRAME_FLAGS_LAST RT_BIT(1)
738/** This is the last record because we detected a loop. */
739#define DBGFSTACKFRAME_FLAGS_LOOP RT_BIT(2)
740/** This is the last record because we reached the maximum depth. */
741#define DBGFSTACKFRAME_FLAGS_MAX_DEPTH RT_BIT(3)
742/** @} */
743
744VMMR3DECL(int) DBGFR3StackWalkBeginGuest(PVM pVM, PDBGFSTACKFRAME pFrame);
745VMMR3DECL(int) DBGFR3StackWalkBeginHyper(PVM pVM, PDBGFSTACKFRAME pFrame);
746VMMR3DECL(int) DBGFR3StackWalkNext(PVM pVM, PDBGFSTACKFRAME pFrame);
747VMMR3DECL(void) DBGFR3StackWalkEnd(PVM pVM, PDBGFSTACKFRAME pFrame);
748
749
750
751
752/** Flags to pass to DBGFR3DisasInstrEx().
753 * @{ */
754/** Disassemble the current guest instruction, with annotations. */
755#define DBGF_DISAS_FLAGS_CURRENT_GUEST RT_BIT(0)
756/** Disassemble the current hypervisor instruction, with annotations. */
757#define DBGF_DISAS_FLAGS_CURRENT_HYPER RT_BIT(1)
758/** No annotations for current context. */
759#define DBGF_DISAS_FLAGS_NO_ANNOTATION RT_BIT(2)
760/** No symbol lookup. */
761#define DBGF_DISAS_FLAGS_NO_SYMBOLS RT_BIT(3)
762/** No instruction bytes. */
763#define DBGF_DISAS_FLAGS_NO_BYTES RT_BIT(4)
764/** No address in the output. */
765#define DBGF_DISAS_FLAGS_NO_ADDRESS RT_BIT(5)
766/** @} */
767
768/** Special flat selector. */
769#define DBGF_SEL_FLAT 1
770
771VMMR3DECL(int) DBGFR3DisasInstrEx(PVM pVM, PVMCPU pVCpu, RTSEL Sel, RTGCPTR GCPtr, unsigned fFlags, char *pszOutput, uint32_t cchOutput, uint32_t *pcbInstr);
772VMMR3DECL(int) DBGFR3DisasInstr(PVM pVM, PVMCPU pVCpu, RTSEL Sel, RTGCPTR GCPtr, char *pszOutput, uint32_t cbOutput);
773VMMR3DECL(int) DBGFR3DisasInstrCurrent(PVM pVM, char *pszOutput, uint32_t cbOutput);
774VMMR3DECL(int) DBGFR3DisasInstrCurrentLogInternal(PVM pVM, const char *pszPrefix);
775
776/** @def DBGFR3DisasInstrCurrentLog
777 * Disassembles the current guest context instruction and writes it to the log.
778 * All registers and data will be displayed. Addresses will be attempted resolved to symbols.
779 */
780#ifdef LOG_ENABLED
781# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) \
782 do { \
783 if (LogIsEnabled()) \
784 DBGFR3DisasInstrCurrentLogInternal(pVM, pszPrefix); \
785 } while (0)
786#else
787# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) do { } while (0)
788#endif
789
790VMMR3DECL(int) DBGFR3DisasInstrLogInternal(PVM pVM, PVMCPU pVCpu, RTSEL Sel, RTGCPTR GCPtr);
791
792/** @def DBGFR3DisasInstrLog
793 * Disassembles the specified guest context instruction and writes it to the log.
794 * Addresses will be attempted resolved to symbols.
795 */
796#ifdef LOG_ENABLED
797# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) \
798 do { \
799 if (LogIsEnabled()) \
800 DBGFR3DisasInstrLogInternal(pVM, Sel, GCPtr); \
801 } while (0)
802#else
803# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) do { } while (0)
804#endif
805
806
807VMMR3DECL(int) DBGFR3MemScan(PVM pVM, PCDBGFADDRESS pAddress, RTGCUINTPTR cbRange, const uint8_t *pabNeedle, size_t cbNeedle, PDBGFADDRESS pHitAddress);
808VMMR3DECL(int) DBGFR3MemRead(PVM pVM, PCDBGFADDRESS pAddress, void *pvBuf, size_t cbRead);
809VMMR3DECL(int) DBGFR3MemReadString(PVM pVM, PCDBGFADDRESS pAddress, char *pszBuf, size_t cbBuf);
810VMMR3DECL(int) DBGFR3ReadGCVirt(PVM pVM, PVMCPU pVCpu, void *pvDst, RTGCPTR GCPtr, size_t cb);
811VMMR3DECL(int) DBGFR3WriteGCVirt(PVM pVM, PVMCPU pVCpu, RTGCPTR GCPtrDst, const void *pvSrc, size_t cb);
812
813
814/**
815 * Guest OS digger interface identifier.
816 *
817 * This is for use together with PDBGFR3QueryInterface and is used to
818 * obtain access to optional interfaces.
819 */
820typedef enum DBGFOSINTERFACE
821{
822 /** The usual invalid entry. */
823 DBGFOSINTERFACE_INVALID = 0,
824 /** Process info. */
825 DBGFOSINTERFACE_PROCESS,
826 /** Thread info. */
827 DBGFOSINTERFACE_THREAD,
828 /** The end of the valid entries. */
829 DBGFOSINTERFACE_END,
830 /** The usual 32-bit type blowup. */
831 DBGFOSINTERFACE_32BIT_HACK = 0x7fffffff
832} DBGFOSINTERFACE;
833/** Pointer to a Guest OS digger interface identifier. */
834typedef DBGFOSINTERFACE *PDBGFOSINTERFACE;
835/** Pointer to a const Guest OS digger interface identifier. */
836typedef DBGFOSINTERFACE const *PCDBGFOSINTERFACE;
837
838
839/**
840 * Guest OS Digger Registration Record.
841 *
842 * This is used with the DBGFR3OSRegister() API.
843 */
844typedef struct DBGFOSREG
845{
846 /** Magic value (DBGFOSREG_MAGIC). */
847 uint32_t u32Magic;
848 /** Flags. Reserved. */
849 uint32_t fFlags;
850 /** The size of the instance data. */
851 uint32_t cbData;
852 /** Operative System name. */
853 char szName[24];
854
855 /**
856 * Constructs the instance.
857 *
858 * @returns VBox status code.
859 * @param pVM Pointer to the shared VM structure.
860 * @param pvData Pointer to the instance data.
861 */
862 DECLCALLBACKMEMBER(int, pfnConstruct)(PVM pVM, void *pvData);
863
864 /**
865 * Destroys the instance.
866 *
867 * @param pVM Pointer to the shared VM structure.
868 * @param pvData Pointer to the instance data.
869 */
870 DECLCALLBACKMEMBER(void, pfnDestruct)(PVM pVM, void *pvData);
871
872 /**
873 * Probes the guest memory for OS finger prints.
874 *
875 * No setup or so is performed, it will be followed by a call to pfnInit
876 * or pfnRefresh that should take care of that.
877 *
878 * @returns true if is an OS handled by this module, otherwise false.
879 * @param pVM Pointer to the shared VM structure.
880 * @param pvData Pointer to the instance data.
881 */
882 DECLCALLBACKMEMBER(bool, pfnProbe)(PVM pVM, void *pvData);
883
884 /**
885 * Initializes a fresly detected guest, loading symbols and such useful stuff.
886 *
887 * This is called after pfnProbe.
888 *
889 * @returns VBox status code.
890 * @param pVM Pointer to the shared VM structure.
891 * @param pvData Pointer to the instance data.
892 */
893 DECLCALLBACKMEMBER(int, pfnInit)(PVM pVM, void *pvData);
894
895 /**
896 * Refreshes symbols and stuff following a redetection of the same OS.
897 *
898 * This is called after pfnProbe.
899 *
900 * @returns VBox status code.
901 * @param pVM Pointer to the shared VM structure.
902 * @param pvData Pointer to the instance data.
903 */
904 DECLCALLBACKMEMBER(int, pfnRefresh)(PVM pVM, void *pvData);
905
906 /**
907 * Terminates an OS when a new (or none) OS has been detected,
908 * and before destruction.
909 *
910 * This is called after pfnProbe and if needed before pfnDestruct.
911 *
912 * @param pVM Pointer to the shared VM structure.
913 * @param pvData Pointer to the instance data.
914 */
915 DECLCALLBACKMEMBER(void, pfnTerm)(PVM pVM, void *pvData);
916
917 /**
918 * Queries the version of the running OS.
919 *
920 * This is only called after pfnInit().
921 *
922 * @returns VBox status code.
923 * @param pVM Pointer to the shared VM structure.
924 * @param pvData Pointer to the instance data.
925 * @param pszVersion Where to store the version string.
926 * @param cchVersion The size of the version string buffer.
927 */
928 DECLCALLBACKMEMBER(int, pfnQueryVersion)(PVM pVM, void *pvData, char *pszVersion, size_t cchVersion);
929
930 /**
931 * Queries the pointer to a interface.
932 *
933 * This is called after pfnProbe.
934 *
935 * @returns Pointer to the interface if available, NULL if not available.
936 * @param pVM Pointer to the shared VM structure.
937 * @param pvData Pointer to the instance data.
938 * @param enmIf The interface identifier.
939 */
940 DECLCALLBACKMEMBER(void *, pfnQueryInterface)(PVM pVM, void *pvData, DBGFOSINTERFACE enmIf);
941
942 /** Trailing magic (DBGFOSREG_MAGIC). */
943 uint32_t u32EndMagic;
944} DBGFOSREG;
945/** Pointer to a Guest OS digger registration record. */
946typedef DBGFOSREG *PDBGFOSREG;
947/** Pointer to a const Guest OS digger registration record. */
948typedef DBGFOSREG const *PCDBGFOSREG;
949
950/** Magic value for DBGFOSREG::u32Magic and DBGFOSREG::u32EndMagic. (Hitomi Kanehara) */
951#define DBGFOSREG_MAGIC 0x19830808
952
953VMMR3DECL(int) DBGFR3OSRegister(PVM pVM, PCDBGFOSREG pReg);
954VMMR3DECL(int) DBGFR3OSDeregister(PVM pVM, PCDBGFOSREG pReg);
955VMMR3DECL(int) DBGFR3OSDetect(PVM pVM, char *pszName, size_t cchName);
956VMMR3DECL(int) DBGFR3OSQueryNameAndVersion(PVM pVM, char *pszName, size_t cchName, char *pszVersion, size_t cchVersion);
957VMMR3DECL(void *) DBGFR3OSQueryInterface(PVM pVM, DBGFOSINTERFACE enmIf);
958
959/** @} */
960
961
962__END_DECLS
963
964#endif
965
Note: See TracBrowser for help on using the repository browser.

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