VirtualBox

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

Last change on this file since 4878 was 4071, checked in by vboxsync, 17 years ago

Biggest check-in ever. New source code headers for all (C) innotek files.
  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 48.9 KB
Line 
1/** @file
2 * DBGF - Debugging Facility.
3 */
4
5/*
6 * Copyright (C) 2006-2007 innotek GmbH
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 as published by the Free Software Foundation,
12 * in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
13 * distribution. VirtualBox OSE is distributed in the hope that it will
14 * be useful, but WITHOUT ANY WARRANTY of any kind.
15 */
16
17#ifndef ___VBox_dbgf_h
18#define ___VBox_dbgf_h
19
20#include <VBox/cdefs.h>
21#include <VBox/types.h>
22#include <VBox/vmm.h>
23#include <VBox/log.h> /* LOG_ENABLED */
24
25#include <iprt/stdarg.h>
26
27__BEGIN_DECLS
28
29
30/** @defgroup grp_dbgf The Debugging Facility API
31 * @{
32 */
33
34#ifdef IN_GC
35/** @addgroup grp_dbgf_gc The GC DBGF API
36 * @ingroup grp_dbgf
37 * @{
38 */
39
40/**
41 * \#DB (Debug event) handler.
42 *
43 * @returns VBox status code.
44 * VINF_SUCCESS means we completely handled this trap,
45 * other codes are passed execution to host context.
46 *
47 * @param pVM The VM handle.
48 * @param pRegFrame Pointer to the register frame for the trap.
49 * @param uDr6 The DR6 register value.
50 */
51DBGFGCDECL(int) DBGFGCTrap01Handler(PVM pVM, PCPUMCTXCORE pRegFrame, RTUINTREG uDr6);
52
53/**
54 * \#BP (Breakpoint) handler.
55 *
56 * @returns VBox status code.
57 * VINF_SUCCESS means we completely handled this trap,
58 * other codes are passed execution to host context.
59 *
60 * @param pVM The VM handle.
61 * @param pRegFrame Pointer to the register frame for the trap.
62 */
63DBGFGCDECL(int) DBGFGCTrap03Handler(PVM pVM, PCPUMCTXCORE pRegFrame);
64
65/** @} */
66#endif
67
68#ifdef IN_RING0
69/** @addgroup grp_dbgf_gc The R0 DBGF API
70 * @ingroup grp_dbgf
71 * @{
72 */
73
74/**
75 * \#DB (Debug event) handler.
76 *
77 * @returns VBox status code.
78 * VINF_SUCCESS means we completely handled this trap,
79 * other codes are passed execution to host context.
80 *
81 * @param pVM The VM handle.
82 * @param pRegFrame Pointer to the register frame for the trap.
83 * @param uDr6 The DR6 register value.
84 */
85DBGFR0DECL(int) DBGFR0Trap01Handler(PVM pVM, PCPUMCTXCORE pRegFrame, RTUINTREG uDr6);
86
87/**
88 * \#BP (Breakpoint) handler.
89 *
90 * @returns VBox status code.
91 * VINF_SUCCESS means we completely handled this trap,
92 * other codes are passed execution to host context.
93 *
94 * @param pVM The VM handle.
95 * @param pRegFrame Pointer to the register frame for the trap.
96 */
97DBGFR0DECL(int) DBGFR0Trap03Handler(PVM pVM, PCPUMCTXCORE pRegFrame);
98
99/** @} */
100#endif
101
102
103
104/**
105 * Mixed address.
106 */
107typedef struct DBGFADDRESS
108{
109 /** The flat address. */
110 RTGCUINTPTR FlatPtr;
111 /** The selector offset address. */
112 RTGCUINTPTR off;
113 /** The selector. DBGF_SEL_FLAT is a legal value. */
114 RTSEL Sel;
115 /** Flags describing further details about the address. */
116 uint16_t fFlags;
117} DBGFADDRESS;
118/** Pointer to a mixed address. */
119typedef DBGFADDRESS *PDBGFADDRESS;
120/** Pointer to a const mixed address. */
121typedef const DBGFADDRESS *PCDBGFADDRESS;
122
123/** @name DBGFADDRESS Flags.
124 * @{ */
125/** A 16:16 far address. */
126#define DBGFADDRESS_FLAGS_FAR16 0
127/** A 16:32 far address. */
128#define DBGFADDRESS_FLAGS_FAR32 1
129/** A 16:64 far address. */
130#define DBGFADDRESS_FLAGS_FAR64 2
131/** A flat address. */
132#define DBGFADDRESS_FLAGS_FLAT 3
133/** The address type mask. */
134#define DBGFADDRESS_FLAGS_TYPE_MASK 3
135
136/** Set if the address is valid. */
137#define DBGFADDRESS_FLAGS_VALID BIT(2)
138
139/** The address is within the hypervisor memoary area (HMA).
140 * If not set, the address can be assumed to be a guest address. */
141#define DBGFADDRESS_FLAGS_HMA BIT(3)
142
143/** Checks if the mixed address is flat or not. */
144#define DBGFADDRESS_IS_FLAT(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FLAT )
145/** Checks if the mixed address is far 16:16 or not. */
146#define DBGFADDRESS_IS_FAR16(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR16 )
147/** Checks if the mixed address is far 16:32 or not. */
148#define DBGFADDRESS_IS_FAR32(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR32 )
149/** Checks if the mixed address is far 16:64 or not. */
150#define DBGFADDRESS_IS_FAR64(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR64 )
151/** Checks if the mixed address is valid. */
152#define DBGFADDRESS_IS_VALID(pAddress) ( (pAddress)->fFlags & DBGFADDRESS_FLAGS_VALID )
153/** @} */
154
155/**
156 * Creates a mixed address from a Sel:off pair.
157 *
158 * @returns VBox status code.
159 * @param pVM The VM handle.
160 * @param pAddress Where to store the mixed address.
161 * @param Sel The selector part.
162 * @param off The offset part.
163 */
164DBGFR3DECL(int) DBGFR3AddrFromSelOff(PVM pVM, PDBGFADDRESS pAddress, RTSEL Sel, RTUINTPTR off);
165
166/**
167 * Creates a mixed address from a flat address.
168 *
169 * @param pVM The VM handle.
170 * @param pAddress Where to store the mixed address.
171 * @param FlatPtr The flat pointer.
172 */
173DBGFR3DECL(void) DBGFR3AddrFromFlat(PVM pVM, PDBGFADDRESS pAddress, RTGCUINTPTR FlatPtr);
174
175/**
176 * Checks if the specified address is valid (checks the structure pointer too).
177 *
178 * @returns true if valid.
179 * @returns false if invalid.
180 * @param pVM The VM handle.
181 * @param pAddress The address to validate.
182 */
183DBGFR3DECL(bool) DBGFR3AddrIsValid(PVM pVM, PCDBGFADDRESS pAddress);
184
185
186
187
188/**
189 * VMM Debug Event Type.
190 */
191typedef enum DBGFEVENTTYPE
192{
193 /** Halt completed.
194 * This notifies that a halt command have been successfully completed.
195 */
196 DBGFEVENT_HALT_DONE = 0,
197 /** Detach completed.
198 * This notifies that the detach command have been successfully completed.
199 */
200 DBGFEVENT_DETACH_DONE,
201 /** The command from the debugger is not recognized.
202 * This means internal error or half implemented features.
203 */
204 DBGFEVENT_INVALID_COMMAND,
205
206
207 /** Fatal error.
208 * This notifies a fatal error in the VMM and that the debugger get's a
209 * chance to first hand information about the the problem.
210 */
211 DBGFEVENT_FATAL_ERROR = 100,
212 /** Breakpoint Hit.
213 * This notifies that a breakpoint installed by the debugger was hit. The
214 * identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
215 */
216 DBGFEVENT_BREAKPOINT,
217 /** Breakpoint Hit in the Hypervisor.
218 * This notifies that a breakpoint installed by the debugger was hit. The
219 * identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
220 */
221 DBGFEVENT_BREAKPOINT_HYPER,
222 /** Assertion in the Hypervisor (breakpoint instruction).
223 * This notifies that a breakpoint instruction was hit in the hypervisor context.
224 */
225 DBGFEVENT_ASSERTION_HYPER,
226 /** Single Stepped.
227 * This notifies that a single step operation was completed.
228 */
229 DBGFEVENT_STEPPED,
230 /** Single Stepped.
231 * This notifies that a hypervisor single step operation was completed.
232 */
233 DBGFEVENT_STEPPED_HYPER,
234 /** The developer have used the DBGFSTOP macro or the PDMDeviceDBGFSTOP function
235 * to bring up the debugger at a specific place.
236 */
237 DBGFEVENT_DEV_STOP,
238 /** The VM is terminating.
239 * When this notification is received, the debugger thread should detach ASAP.
240 */
241 DBGFEVENT_TERMINATING,
242
243 /** The usual 32-bit hack. */
244 DBGFEVENT_32BIT_HACK = 0x7fffffff
245} DBGFEVENTTYPE;
246
247
248/**
249 * The context of an event.
250 */
251typedef enum DBGFEVENTCTX
252{
253 /** The usual invalid entry. */
254 DBGFEVENTCTX_INVALID = 0,
255 /** Raw mode. */
256 DBGFEVENTCTX_RAW,
257 /** Recompiled mode. */
258 DBGFEVENTCTX_REM,
259 /** VMX / AVT mode. */
260 DBGFEVENTCTX_HWACCL,
261 /** Hypervisor context. */
262 DBGFEVENTCTX_HYPER,
263 /** Other mode */
264 DBGFEVENTCTX_OTHER,
265
266 /** The usual 32-bit hack */
267 DBGFEVENTCTX_32BIT_HACK = 0x7fffffff
268} DBGFEVENTCTX;
269
270/**
271 * VMM Debug Event.
272 */
273typedef struct DBGFEVENT
274{
275 /** Type. */
276 DBGFEVENTTYPE enmType;
277 /** Context */
278 DBGFEVENTCTX enmCtx;
279 /** Type specific data. */
280 union
281 {
282 /** Fatal error details. */
283 struct
284 {
285 /** The GC return code. */
286 int rc;
287 } FatalError;
288
289 /** Source location. */
290 struct
291 {
292 /** File name. */
293 R3PTRTYPE(const char *) pszFile;
294 /** Function name. */
295 R3PTRTYPE(const char *) pszFunction;
296 /** Message. */
297 R3PTRTYPE(const char *) pszMessage;
298 /** Line number. */
299 unsigned uLine;
300 } Src;
301
302 /** Assertion messages. */
303 struct
304 {
305 /** The first message. */
306 R3PTRTYPE(const char *) pszMsg1;
307 /** The second message. */
308 R3PTRTYPE(const char *) pszMsg2;
309 } Assert;
310
311 /** Breakpoint. */
312 struct DBGFEVENTBP
313 {
314 /** The identifier of the breakpoint which was hit. */
315 RTUINT iBp;
316 } Bp;
317 /** Padding for ensuring that the structure is 8 byte aligned. */
318 uint64_t au64Padding[4];
319 } u;
320} DBGFEVENT;
321/** Pointer to VMM Debug Event. */
322typedef DBGFEVENT *PDBGFEVENT;
323/** Pointer to const VMM Debug Event. */
324typedef const DBGFEVENT *PCDBGFEVENT;
325
326
327/** @def DBGFSTOP
328 * Stops the debugger raising a DBGFEVENT_DEVELOPER_STOP event.
329 *
330 * @returns VBox status code which must be propagated up to EM if not VINF_SUCCESS.
331 * @param pVM VM Handle.
332 */
333#ifdef VBOX_STRICT
334# define DBGFSTOP(pVM) DBGFR3EventSrc(pVM, DBGFEVENT_DEV_STOP, __FILE__, __LINE__, __PRETTY_FUNCTION__, NULL)
335#else
336# define DBGFSTOP(pVM) VINF_SUCCESS
337#endif
338
339/**
340 * Initializes the DBGF.
341 *
342 * @returns VBox status code.
343 * @param pVM VM handle.
344 */
345DBGFR3DECL(int) DBGFR3Init(PVM pVM);
346
347/**
348 * Termiantes and cleans up resources allocated by the DBGF.
349 *
350 * @returns VBox status code.
351 * @param pVM VM Handle.
352 */
353DBGFR3DECL(int) DBGFR3Term(PVM pVM);
354
355/**
356 * Applies relocations to data and code managed by this
357 * component. This function will be called at init and
358 * whenever the VMM need to relocate it self inside the GC.
359 *
360 * @param pVM VM handle.
361 * @param offDelta Relocation delta relative to old location.
362 */
363DBGFR3DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta);
364
365/**
366 * Forced action callback.
367 * The VMM will call this from it's main loop when VM_FF_DBGF is set.
368 *
369 * The function checks and executes pending commands from the debugger.
370 *
371 * @returns VINF_SUCCESS normally.
372 * @returns VERR_DBGF_RAISE_FATAL_ERROR to pretend a fatal error happend.
373 * @param pVM VM Handle.
374 */
375DBGFR3DECL(int) DBGFR3VMMForcedAction(PVM pVM);
376
377/**
378 * Send a generic debugger event which takes no data.
379 *
380 * @returns VBox status.
381 * @param pVM The VM handle.
382 * @param enmEvent The event to send.
383 */
384DBGFR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent);
385
386/**
387 * Send a debugger event which takes the full source file location.
388 *
389 * @returns VBox status.
390 * @param pVM The VM handle.
391 * @param enmEvent The event to send.
392 * @param pszFile Source file.
393 * @param uLine Line number in source file.
394 * @param pszFunction Function name.
395 * @param pszFormat Message which accompanies the event.
396 * @param ... Message arguments.
397 */
398DBGFR3DECL(int) DBGFR3EventSrc(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine, const char *pszFunction, const char *pszFormat, ...);
399
400/**
401 * Send a debugger event which takes the full source file location.
402 *
403 * @returns VBox status.
404 * @param pVM The VM handle.
405 * @param enmEvent The event to send.
406 * @param pszFile Source file.
407 * @param uLine Line number in source file.
408 * @param pszFunction Function name.
409 * @param pszFormat Message which accompanies the event.
410 * @param args Message arguments.
411 */
412DBGFR3DECL(int) DBGFR3EventSrcV(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine, const char *pszFunction, const char *pszFormat, va_list args);
413
414/**
415 * Send a debugger event which takes the two assertion messages.
416 *
417 * @returns VBox status.
418 * @param pVM The VM handle.
419 * @param enmEvent The event to send.
420 * @param pszMsg1 First assertion message.
421 * @param pszMsg2 Second assertion message.
422 */
423DBGFR3DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszMsg1, const char *pszMsg2);
424
425/**
426 * Breakpoint was hit somewhere.
427 * Figure out which breakpoint it is and notify the debugger.
428 *
429 * @returns VBox status.
430 * @param pVM The VM handle.
431 * @param enmEvent DBGFEVENT_BREAKPOINT_HYPER or DBGFEVENT_BREAKPOINT.
432 */
433DBGFR3DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent);
434
435/**
436 * Attaches a debugger to the specified VM.
437 *
438 * Only one debugger at a time.
439 *
440 * @returns VBox status code.
441 * @param pVM VM Handle.
442 */
443DBGFR3DECL(int) DBGFR3Attach(PVM pVM);
444
445/**
446 * Detaches a debugger from the specified VM.
447 *
448 * Caller must be attached to the VM.
449 *
450 * @returns VBox status code.
451 * @param pVM VM Handle.
452 */
453DBGFR3DECL(int) DBGFR3Detach(PVM pVM);
454
455/**
456 * Wait for a debug event.
457 *
458 * @returns VBox status. Will not return VBOX_INTERRUPTED.
459 * @param pVM VM handle.
460 * @param cMillies Number of millies to wait.
461 * @param ppEvent Where to store the event pointer.
462 */
463DBGFR3DECL(int) DBGFR3EventWait(PVM pVM, unsigned cMillies, PCDBGFEVENT *ppEvent);
464
465/**
466 * Halts VM execution.
467 *
468 * After calling this the VM isn't actually halted till an DBGFEVENT_HALT_DONE
469 * arrives. Until that time it's not possible to issue any new commands.
470 *
471 * @returns VBox status.
472 * @param pVM VM handle.
473 */
474DBGFR3DECL(int) DBGFR3Halt(PVM pVM);
475
476/**
477 * Checks if the VM is halted by the debugger.
478 *
479 * @returns True if halted.
480 * @returns False if not halted.
481 * @param pVM VM handle.
482 */
483DBGFR3DECL(bool) DBGFR3IsHalted(PVM pVM);
484
485/**
486 * Checks if the the debugger can wait for events or not.
487 *
488 * This function is only used by lazy, multiplexing debuggers. :-)
489 *
490 * @returns True if waitable.
491 * @returns False if not waitable.
492 * @param pVM VM handle.
493 */
494DBGFR3DECL(bool) DBGFR3CanWait(PVM pVM);
495
496/**
497 * Resumes VM execution.
498 *
499 * There is no receipt event on this command.
500 *
501 * @returns VBox status.
502 * @param pVM VM handle.
503 */
504DBGFR3DECL(int) DBGFR3Resume(PVM pVM);
505
506/**
507 * Step Into.
508 *
509 * A single step event is generated from this command.
510 * The current implementation is not reliable, so don't rely on the event comming.
511 *
512 * @returns VBox status.
513 * @param pVM VM handle.
514 */
515DBGFR3DECL(int) DBGFR3Step(PVM pVM);
516
517/**
518 * Call this to single step rawmode or recompiled mode.
519 *
520 * You must pass down the return code to the EM loop! That's
521 * where the actual single stepping take place (at least in the
522 * current implementation).
523 *
524 * @returns VINF_EM_DBG_STEP
525 * @thread EMT
526 */
527DBGFR3DECL(int) DBGFR3PrgStep(PVM pVM);
528
529
530/** Breakpoint type. */
531typedef enum DBGFBPTYPE
532{
533 /** Free breakpoint entry. */
534 DBGFBPTYPE_FREE = 0,
535 /** Debug register. */
536 DBGFBPTYPE_REG,
537 /** INT 3 instruction. */
538 DBGFBPTYPE_INT3,
539 /** Recompiler. */
540 DBGFBPTYPE_REM,
541 /** ensure 32-bit size. */
542 DBGFBPTYPE_32BIT_HACK = 0x7fffffff
543} DBGFBPTYPE;
544
545
546/**
547 * A Breakpoint.
548 */
549typedef struct DBGFBP
550{
551 /** The number of breakpoint hits. */
552 uint64_t cHits;
553 /** The hit number which starts to trigger the breakpoint. */
554 uint64_t iHitTrigger;
555 /** The hit number which stops triggering the breakpoint (disables it).
556 * Use ~(uint64_t)0 if it should never stop. */
557 uint64_t iHitDisable;
558 /** The Flat GC address of the breakpoint.
559 * (PC register value if REM type?) */
560 RTGCUINTPTR GCPtr;
561 /** The breakpoint id. */
562 RTUINT iBp;
563 /** The breakpoint status - enabled or disabled. */
564 bool fEnabled;
565
566 /** The breakpoint type. */
567 DBGFBPTYPE enmType;
568 /** Union of type specific data. */
569 union
570 {
571 /** Debug register data. */
572 struct DBGFBPREG
573 {
574 /** The debug register number. */
575 uint8_t iReg;
576 /** The access type (one of the X86_DR7_RW_* value). */
577 uint8_t fType;
578 /** The access size. */
579 uint8_t cb;
580 } Reg;
581 /** Recompiler breakpoint data. */
582 struct DBGFBPINT3
583 {
584 /** The byte value we replaced by the INT 3 instruction. */
585 uint8_t bOrg;
586 } Int3;
587
588 /** Recompiler breakpoint data. */
589 struct DBGFBPREM
590 {
591 /** nothing yet */
592 uint8_t fDummy;
593 } Rem;
594 /** Paddind to ensure that the size is identical on win32 and linux. */
595 uint64_t u64Padding;
596 } u;
597} DBGFBP;
598
599/** Pointer to a breakpoint. */
600typedef DBGFBP *PDBGFBP;
601/** Pointer to a const breakpoint. */
602typedef const DBGFBP *PCDBGFBP;
603
604
605/**
606 * Sets a breakpoint (int 3 based).
607 *
608 * @returns VBox status code.
609 * @param pVM The VM handle.
610 * @param pAddress The address of the breakpoint.
611 * @param iHitTrigger The hit count at which the breakpoint start triggering.
612 * Use 0 (or 1) if it's gonna trigger at once.
613 * @param iHitDisable The hit count which disables the breakpoint.
614 * Use ~(uint64_t) if it's never gonna be disabled.
615 * @param piBp Where to store the breakpoint id. (optional)
616 * @thread Any thread.
617 */
618DBGFR3DECL(int) DBGFR3BpSet(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, PRTUINT piBp);
619
620/**
621 * Sets a register breakpoint.
622 *
623 * @returns VBox status code.
624 * @param pVM The VM handle.
625 * @param pAddress The address of the breakpoint.
626 * @param iHitTrigger The hit count at which the breakpoint start triggering.
627 * Use 0 (or 1) if it's gonna trigger at once.
628 * @param iHitDisable The hit count which disables the breakpoint.
629 * Use ~(uint64_t) if it's never gonna be disabled.
630 * @param fType The access type (one of the X86_DR7_RW_* defines).
631 * @param cb The access size - 1,2,4 or 8 (the latter is AMD64 long mode only.
632 * Must be 1 if fType is X86_DR7_RW_EO.
633 * @param piBp Where to store the breakpoint id. (optional)
634 * @thread Any thread.
635 */
636DBGFR3DECL(int) DBGFR3BpSetReg(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable,
637 uint8_t fType, uint8_t cb, PRTUINT piBp);
638
639/**
640 * Sets a recompiler breakpoint.
641 *
642 * @returns VBox status code.
643 * @param pVM The VM handle.
644 * @param pAddress The address of the breakpoint.
645 * @param iHitTrigger The hit count at which the breakpoint start triggering.
646 * Use 0 (or 1) if it's gonna trigger at once.
647 * @param iHitDisable The hit count which disables the breakpoint.
648 * Use ~(uint64_t) if it's never gonna be disabled.
649 * @param piBp Where to store the breakpoint id. (optional)
650 * @thread Any thread.
651 */
652DBGFR3DECL(int) DBGFR3BpSetREM(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, PRTUINT piBp);
653
654/**
655 * Clears a breakpoint.
656 *
657 * @returns VBox status code.
658 * @param pVM The VM handle.
659 * @param iBp The id of the breakpoint which should be removed (cleared).
660 * @thread Any thread.
661 */
662DBGFR3DECL(int) DBGFR3BpClear(PVM pVM, RTUINT iBp);
663
664/**
665 * Enables a breakpoint.
666 *
667 * @returns VBox status code.
668 * @param pVM The VM handle.
669 * @param iBp The id of the breakpoint which should be enabled.
670 * @thread Any thread.
671 */
672DBGFR3DECL(int) DBGFR3BpEnable(PVM pVM, RTUINT iBp);
673
674/**
675 * Disables a breakpoint.
676 *
677 * @returns VBox status code.
678 * @param pVM The VM handle.
679 * @param iBp The id of the breakpoint which should be disabled.
680 * @thread Any thread.
681 */
682DBGFR3DECL(int) DBGFR3BpDisable(PVM pVM, RTUINT iBp);
683
684/**
685 * Breakpoint enumeration callback function.
686 *
687 * @returns VBox status code. Any failure will stop the enumeration.
688 * @param pVM The VM handle.
689 * @param pvUser The user argument.
690 * @param pBp Pointer to the breakpoint information. (readonly)
691 */
692typedef DECLCALLBACK(int) FNDBGFBPENUM(PVM pVM, void *pvUser, PCDBGFBP pBp);
693/** Pointer to a breakpoint enumeration callback function. */
694typedef FNDBGFBPENUM *PFNDBGFBPENUM;
695
696/**
697 * Enumerate the breakpoints.
698 *
699 * @returns VBox status code.
700 * @param pVM The VM handle.
701 * @param pfnCallback The callback function.
702 * @param pvUser The user argument to pass to the callback.
703 * @thread Any thread but the callback will be called from EMT.
704 */
705DBGFR3DECL(int) DBGFR3BpEnum(PVM pVM, PFNDBGFBPENUM pfnCallback, void *pvUser);
706
707
708/**
709 * Gets the hardware breakpoint configuration as DR7.
710 *
711 * @returns DR7 from the DBGF point of view.
712 * @param pVM The VM handle.
713 */
714DBGFDECL(RTGCUINTREG) DBGFBpGetDR7(PVM pVM);
715
716/**
717 * Gets the address of the hardware breakpoint number 0.
718 *
719 * @returns DR0 from the DBGF point of view.
720 * @param pVM The VM handle.
721 */
722DBGFDECL(RTGCUINTREG) DBGFBpGetDR0(PVM pVM);
723
724/**
725 * Gets the address of the hardware breakpoint number 1.
726 *
727 * @returns DR1 from the DBGF point of view.
728 * @param pVM The VM handle.
729 */
730DBGFDECL(RTGCUINTREG) DBGFBpGetDR1(PVM pVM);
731
732/**
733 * Gets the address of the hardware breakpoint number 2.
734 *
735 * @returns DR2 from the DBGF point of view.
736 * @param pVM The VM handle.
737 */
738DBGFDECL(RTGCUINTREG) DBGFBpGetDR2(PVM pVM);
739
740/**
741 * Gets the address of the hardware breakpoint number 3.
742 *
743 * @returns DR3 from the DBGF point of view.
744 * @param pVM The VM handle.
745 */
746DBGFDECL(RTGCUINTREG) DBGFBpGetDR3(PVM pVM);
747
748/**
749 * Returns single stepping state
750 *
751 * @returns stepping or not
752 * @param pVM The VM handle.
753 */
754DBGFDECL(bool) DBGFIsStepping(PVM pVM);
755
756
757/** Pointer to a info helper callback structure. */
758typedef struct DBGFINFOHLP *PDBGFINFOHLP;
759/** Pointer to a const info helper callback structure. */
760typedef const struct DBGFINFOHLP *PCDBGFINFOHLP;
761
762/**
763 * Info helper callback structure.
764 */
765typedef struct DBGFINFOHLP
766{
767 /**
768 * Print formatted string.
769 *
770 * @param pHlp Pointer to this structure.
771 * @param pszFormat The format string.
772 * @param ... Arguments.
773 */
774 DECLCALLBACKMEMBER(void, pfnPrintf)(PCDBGFINFOHLP pHlp, const char *pszFormat, ...);
775
776 /**
777 * Print formatted string.
778 *
779 * @param pHlp Pointer to this structure.
780 * @param pszFormat The format string.
781 * @param args Argument list.
782 */
783 DECLCALLBACKMEMBER(void, pfnPrintfV)(PCDBGFINFOHLP pHlp, const char *pszFormat, va_list args);
784} DBGFINFOHLP;
785
786
787/**
788 * Info handler, device version.
789 *
790 * @param pDevIns Device instance which registered the info.
791 * @param pHlp Callback functions for doing output.
792 * @param pszArgs Argument string. Optional and specific to the handler.
793 */
794typedef DECLCALLBACK(void) FNDBGFHANDLERDEV(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
795/** Pointer to a FNDBGFHANDLERDEV function. */
796typedef FNDBGFHANDLERDEV *PFNDBGFHANDLERDEV;
797
798/**
799 * Info handler, driver version.
800 *
801 * @param pDrvIns Driver instance which registered the info.
802 * @param pHlp Callback functions for doing output.
803 * @param pszArgs Argument string. Optional and specific to the handler.
804 */
805typedef DECLCALLBACK(void) FNDBGFHANDLERDRV(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
806/** Pointer to a FNDBGFHANDLERDRV function. */
807typedef FNDBGFHANDLERDRV *PFNDBGFHANDLERDRV;
808
809/**
810 * Info handler, internal version.
811 *
812 * @param pVM The VM handle.
813 * @param pHlp Callback functions for doing output.
814 * @param pszArgs Argument string. Optional and specific to the handler.
815 */
816typedef DECLCALLBACK(void) FNDBGFHANDLERINT(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs);
817/** Pointer to a FNDBGFHANDLERINT function. */
818typedef FNDBGFHANDLERINT *PFNDBGFHANDLERINT;
819
820/**
821 * Info handler, external version.
822 *
823 * @param pvUser User argument.
824 * @param pHlp Callback functions for doing output.
825 * @param pszArgs Argument string. Optional and specific to the handler.
826 */
827typedef DECLCALLBACK(void) FNDBGFHANDLEREXT(void *pvUser, PCDBGFINFOHLP pHlp, const char *pszArgs);
828/** Pointer to a FNDBGFHANDLEREXT function. */
829typedef FNDBGFHANDLEREXT *PFNDBGFHANDLEREXT;
830
831
832/** @name Flags for the info registration functions.
833 * @{ */
834/** The handler must run on the EMT. */
835#define DBGFINFO_FLAGS_RUN_ON_EMT BIT(0)
836/** @} */
837
838
839/**
840 * Register a info handler owned by a device.
841 *
842 * @returns VBox status code.
843 * @param pVM VM handle.
844 * @param pszName The identifier of the info.
845 * @param pszDesc The description of the info and any arguments the handler may take.
846 * @param pfnHandler The handler function to be called to display the info.
847 * @param pDevIns The device instance owning the info.
848 */
849DBGFR3DECL(int) DBGFR3InfoRegisterDevice(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler, PPDMDEVINS pDevIns);
850
851/**
852 * Register a info handler owned by a driver.
853 *
854 * @returns VBox status code.
855 * @param pVM VM handle.
856 * @param pszName The identifier of the info.
857 * @param pszDesc The description of the info and any arguments the handler may take.
858 * @param pfnHandler The handler function to be called to display the info.
859 * @param pDrvIns The driver instance owning the info.
860 */
861DBGFR3DECL(int) DBGFR3InfoRegisterDriver(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDRV pfnHandler, PPDMDRVINS pDrvIns);
862
863/**
864 * Register a info handler owned by an internal component.
865 *
866 * @returns VBox status code.
867 * @param pVM VM handle.
868 * @param pszName The identifier of the info.
869 * @param pszDesc The description of the info and any arguments the handler may take.
870 * @param pfnHandler The handler function to be called to display the info.
871 */
872DBGFR3DECL(int) DBGFR3InfoRegisterInternal(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERINT pfnHandler);
873
874/**
875 * Register a info handler owned by an internal component.
876 *
877 * @returns VBox status code.
878 * @param pVM VM handle.
879 * @param pszName The identifier of the info.
880 * @param pszDesc The description of the info and any arguments the handler may take.
881 * @param pfnHandler The handler function to be called to display the info.
882 * @param fFlags Flags, see the DBGFINFO_FLAGS_*.
883 */
884DBGFR3DECL(int) DBGFR3InfoRegisterInternalEx(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERINT pfnHandler, uint32_t fFlags);
885
886/**
887 * Register a info handler owned by an external component.
888 *
889 * @returns VBox status code.
890 * @param pVM VM handle.
891 * @param pszName The identifier of the info.
892 * @param pszDesc The description of the info and any arguments the handler may take.
893 * @param pfnHandler The handler function to be called to display the info.
894 * @param pvUser User argument to be passed to the handler.
895 */
896DBGFR3DECL(int) DBGFR3InfoRegisterExternal(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLEREXT pfnHandler, void *pvUser);
897
898/**
899 * Deregister one(/all) info handler(s) owned by a device.
900 *
901 * @returns VBox status code.
902 * @param pVM VM Handle.
903 * @param pDevIns Device instance.
904 * @param pszName The identifier of the info. If NULL all owned by the device.
905 */
906DBGFR3DECL(int) DBGFR3InfoDeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName);
907
908/**
909 * Deregister one(/all) info handler(s) owned by a driver.
910 *
911 * @returns VBox status code.
912 * @param pVM VM Handle.
913 * @param pDrvIns Driver instance.
914 * @param pszName The identifier of the info. If NULL all owned by the driver.
915 */
916DBGFR3DECL(int) DBGFR3InfoDeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName);
917
918/**
919 * Deregister a info handler owned by an internal component.
920 *
921 * @returns VBox status code.
922 * @param pVM VM Handle.
923 * @param pszName The identifier of the info. If NULL all owned by the device.
924 */
925DBGFR3DECL(int) DBGFR3InfoDeregisterInternal(PVM pVM, const char *pszName);
926
927/**
928 * Deregister a info handler owned by an external component.
929 *
930 * @returns VBox status code.
931 * @param pVM VM Handle.
932 * @param pszName The identifier of the info. If NULL all owned by the device.
933 */
934DBGFR3DECL(int) DBGFR3InfoDeregisterExternal(PVM pVM, const char *pszName);
935
936/**
937 * Display a piece of info writing to the supplied handler.
938 *
939 * @returns VBox status code.
940 * @param pVM VM handle.
941 * @param pszName The identifier of the info to display.
942 * @param pszArgs Arguments to the info handler.
943 * @param pHlp The output helper functions. If NULL the logger will be used.
944 */
945DBGFR3DECL(int) DBGFR3Info(PVM pVM, const char *pszName, const char *pszArgs, PCDBGFINFOHLP pHlp);
946
947/** @def DBGFR3InfoLog
948 * Display a piece of info writing to the log if enabled.
949 *
950 * @param pVM VM handle.
951 * @param pszName The identifier of the info to display.
952 * @param pszArgs Arguments to the info handler.
953 */
954#ifdef LOG_ENABLED
955#define DBGFR3InfoLog(pVM, pszName, pszArgs) \
956 do { \
957 if (LogIsEnabled()) \
958 DBGFR3Info(pVM, pszName, pszArgs, NULL); \
959 } while (0)
960#else
961#define DBGFR3InfoLog(pVM, pszName, pszArgs) do { } while (0)
962#endif
963
964
965/**
966 * Changes the logger group settings.
967 *
968 * @returns VBox status code.
969 * @param pVM The VM handle.
970 * @param pszGroupSettings The group settings string. (VBOX_LOG)
971 */
972DBGFR3DECL(int) DBGFR3LogModifyGroups(PVM pVM, const char *pszGroupSettings);
973
974/**
975 * Changes the logger flag settings.
976 *
977 * @returns VBox status code.
978 * @param pVM The VM handle.
979 * @param pszFlagSettings The flag settings string. (VBOX_LOG_FLAGS)
980 */
981DBGFR3DECL(int) DBGFR3LogModifyFlags(PVM pVM, const char *pszFlagSettings);
982
983/**
984 * Changes the logger destination settings.
985 *
986 * @returns VBox status code.
987 * @param pVM The VM handle.
988 * @param pszDestSettings The destination settings string. (VBOX_LOG_DEST)
989 */
990DBGFR3DECL(int) DBGFR3LogModifyDestinations(PVM pVM, const char *pszDestSettings);
991
992
993/**
994 * Enumeration callback for use with DBGFR3InfoEnum.
995 *
996 * @returns VBox status code.
997 * A status code indicating failure will end the enumeration
998 * and DBGFR3InfoEnum will return with that status code.
999 * @param pVM VM handle.
1000 * @param pszName Info identifier name.
1001 * @param pszDesc The description.
1002 */
1003typedef DECLCALLBACK(int) FNDBGFINFOENUM(PVM pVM, const char *pszName, const char *pszDesc, void *pvUser);
1004/** Pointer to a FNDBGFINFOENUM function. */
1005typedef FNDBGFINFOENUM *PFNDBGFINFOENUM;
1006
1007/**
1008 * Enumerate all the register info handlers.
1009 *
1010 * @returns VBox status code.
1011 * @param pVM VM handle.
1012 * @param pfnCallback Pointer to callback function.
1013 * @param pvUser User argument to pass to the callback.
1014 */
1015DBGFR3DECL(int) DBGFR3InfoEnum(PVM pVM, PFNDBGFINFOENUM pfnCallback, void *pvUser);
1016
1017/**
1018 * Gets the logger info helper.
1019 * The returned info helper will unconditionally write all output to the log.
1020 *
1021 * @returns Pointer to the logger info helper.
1022 */
1023DBGFR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogHlp(void);
1024
1025/**
1026 * Gets the release logger info helper.
1027 * The returned info helper will unconditionally write all output to the release log.
1028 *
1029 * @returns Pointer to the release logger info helper.
1030 */
1031DBGFR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogRelHlp(void);
1032
1033
1034
1035/** Max length (including '\\0') of a symbol name. */
1036#define DBGF_SYMBOL_NAME_LENGTH 512
1037
1038/**
1039 * Debug symbol.
1040 */
1041typedef struct DBGFSYMBOL
1042{
1043 /** Symbol value (address). */
1044 RTGCUINTPTR Value;
1045 /** Symbol size. */
1046 uint32_t cb;
1047 /** Symbol Flags. (reserved). */
1048 uint32_t fFlags;
1049 /** Symbol name. */
1050 char szName[DBGF_SYMBOL_NAME_LENGTH];
1051} DBGFSYMBOL;
1052/** Pointer to debug symbol. */
1053typedef DBGFSYMBOL *PDBGFSYMBOL;
1054/** Pointer to const debug symbol. */
1055typedef const DBGFSYMBOL *PCDBGFSYMBOL;
1056
1057/**
1058 * Debug line number information.
1059 */
1060typedef struct DBGFLINE
1061{
1062 /** Address. */
1063 RTGCUINTPTR Address;
1064 /** Line number. */
1065 uint32_t uLineNo;
1066 /** Filename. */
1067 char szFilename[260];
1068} DBGFLINE;
1069/** Pointer to debug line number. */
1070typedef DBGFLINE *PDBGFLINE;
1071/** Pointer to const debug line number. */
1072typedef const DBGFLINE *PCDBGFLINE;
1073
1074
1075/**
1076 * Load debug info, optionally related to a specific module.
1077 *
1078 * @returns VBox status.
1079 * @param pVM VM Handle.
1080 * @param pszFilename Path to the file containing the symbol information.
1081 * This can be the executable image, a flat symbol file of some kind or stripped debug info.
1082 * @param AddressDelta The value to add to the loaded symbols.
1083 * @param pszName Short hand name for the module. If not related to a module specify NULL.
1084 * @param Address Address which the image is loaded at. This will be used to reference the module other places in the api.
1085 * Ignored when pszName is NULL.
1086 * @param cbImage Size of the image.
1087 * Ignored when pszName is NULL.
1088 */
1089DBGFR3DECL(int) DBGFR3ModuleLoad(PVM pVM, const char *pszFilename, RTGCUINTPTR AddressDelta, const char *pszName, RTGCUINTPTR ModuleAddress, unsigned cbImage);
1090
1091/**
1092 * Interface used by PDMR3LdrRelocate for telling us that a GC module has been relocated.
1093 *
1094 * @param pVM The VM handle.
1095 * @param OldImageBase The old image base.
1096 * @param NewImageBase The new image base.
1097 * @param cbImage The image size.
1098 * @param pszFilename The image filename.
1099 * @param pszName The module name.
1100 */
1101DBGFR3DECL(void) DBGFR3ModuleRelocate(PVM pVM, RTGCUINTPTR OldImageBase, RTGCUINTPTR NewImageBase, unsigned cbImage,
1102 const char *pszFilename, const char *pszName);
1103
1104/**
1105 * Adds a symbol to the debug info manager.
1106 *
1107 * @returns VBox status.
1108 * @param pVM VM Handle.
1109 * @param ModuleAddress Module address. Use 0 if no module.
1110 * @param SymbolAddress Symbol address
1111 * @param cbSymbol Size of the symbol. Use 0 if info not available.
1112 * @param pszSymbol Symbol name.
1113 */
1114DBGFR3DECL(int) DBGFR3SymbolAdd(PVM pVM, RTGCUINTPTR ModuleAddress, RTGCUINTPTR SymbolAddress, RTUINT cbSymbol, const char *pszSymbol);
1115
1116/**
1117 * Find symbol by address (nearest).
1118 *
1119 * @returns VBox status.
1120 * @param pVM VM handle.
1121 * @param Address Address.
1122 * @param poffDisplacement Where to store the symbol displacement from Address.
1123 * @param pSymbol Where to store the symbol info.
1124 */
1125DBGFR3DECL(int) DBGFR3SymbolByAddr(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement, PDBGFSYMBOL pSymbol);
1126
1127/**
1128 * Find symbol by name (first).
1129 *
1130 * @returns VBox status.
1131 * @param pVM VM handle.
1132 * @param pszSymbol Symbol name.
1133 * @param pSymbol Where to store the symbol info.
1134 */
1135DBGFR3DECL(int) DBGFR3SymbolByName(PVM pVM, const char *pszSymbol, PDBGFSYMBOL pSymbol);
1136
1137/**
1138 * Find symbol by address (nearest), allocate return buffer.
1139 *
1140 * @returns Pointer to the symbol. Must be freed using DBGFR3SymbolFree().
1141 * @returns NULL if the symbol was not found or if we're out of memory.
1142 * @param pVM VM handle.
1143 * @param Address Address.
1144 * @param poffDisplacement Where to store the symbol displacement from Address.
1145 */
1146DBGFR3DECL(PDBGFSYMBOL) DBGFR3SymbolByAddrAlloc(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement);
1147
1148/**
1149 * Find symbol by name (first), allocate return buffer.
1150 *
1151 * @returns Pointer to the symbol. Must be freed using DBGFR3SymbolFree().
1152 * @returns NULL if the symbol was not found or if we're out of memory.
1153 * @param pVM VM handle.
1154 * @param pszSymbol Symbol name.
1155 * @param ppSymbol Where to store the pointer to the symbol info.
1156 */
1157DBGFR3DECL(PDBGFSYMBOL) DBGFR3SymbolByNameAlloc(PVM pVM, const char *pszSymbol);
1158
1159/**
1160 * Frees a symbol returned by DBGFR3SymbolbyNameAlloc() or DBGFR3SymbolByAddressAlloc().
1161 *
1162 * @param pSymbol Pointer to the symbol.
1163 */
1164DBGFR3DECL(void) DBGFR3SymbolFree(PDBGFSYMBOL pSymbol);
1165
1166/**
1167 * Find line by address (nearest).
1168 *
1169 * @returns VBox status.
1170 * @param pVM VM handle.
1171 * @param Address Address.
1172 * @param poffDisplacement Where to store the line displacement from Address.
1173 * @param pLine Where to store the line info.
1174 */
1175DBGFR3DECL(int) DBGFR3LineByAddr(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement, PDBGFLINE pLine);
1176
1177/**
1178 * Find line by address (nearest), allocate return buffer.
1179 *
1180 * @returns Pointer to the line. Must be freed using DBGFR3LineFree().
1181 * @returns NULL if the line was not found or if we're out of memory.
1182 * @param pVM VM handle.
1183 * @param Address Address.
1184 * @param poffDisplacement Where to store the line displacement from Address.
1185 */
1186DBGFR3DECL(PDBGFLINE) DBGFR3LineByAddrAlloc(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement);
1187
1188/**
1189 * Frees a line returned by DBGFR3LineByAddressAlloc().
1190 *
1191 * @param pLine Pointer to the line.
1192 */
1193DBGFR3DECL(void) DBGFR3LineFree(PDBGFLINE pLine);
1194
1195/**
1196 * Return type.
1197 */
1198typedef enum DBGFRETRUNTYPE
1199{
1200 /** The usual invalid 0 value. */
1201 DBGFRETURNTYPE_INVALID = 0,
1202 /** Near 16-bit return. */
1203 DBGFRETURNTYPE_NEAR16,
1204 /** Near 32-bit return. */
1205 DBGFRETURNTYPE_NEAR32,
1206 /** Near 64-bit return. */
1207 DBGFRETURNTYPE_NEAR64,
1208 /** Far 16:16 return. */
1209 DBGFRETURNTYPE_FAR16,
1210 /** Far 16:32 return. */
1211 DBGFRETURNTYPE_FAR32,
1212 /** Far 16:64 return. */
1213 DBGFRETURNTYPE_FAR64,
1214 /** 16-bit iret return (e.g. real or 286 protect mode). */
1215 DBGFRETURNTYPE_IRET16,
1216 /** 32-bit iret return. */
1217 DBGFRETURNTYPE_IRET32,
1218 /** 32-bit iret return. */
1219 DBGFRETURNTYPE_IRET32_PRIV,
1220 /** 32-bit iret return to V86 mode. */
1221 DBGFRETURNTYPE_IRET32_V86,
1222 /** @todo 64-bit iret return. */
1223 DBGFRETURNTYPE_IRET64,
1224 /** The usual 32-bit blowup. */
1225 DBGFRETURNTYPE_32BIT_HACK = 0x7fffffff
1226} DBGFRETURNTYPE;
1227
1228
1229/**
1230 * Figures the size of the return state on the stack.
1231 *
1232 * @returns number of bytes. 0 if invalid parameter.
1233 * @param enmRetType The type of return.
1234 */
1235DECLINLINE(unsigned) DBGFReturnTypeSize(DBGFRETURNTYPE enmRetType)
1236{
1237 switch (enmRetType)
1238 {
1239 case DBGFRETURNTYPE_NEAR16: return 2;
1240 case DBGFRETURNTYPE_NEAR32: return 4;
1241 case DBGFRETURNTYPE_NEAR64: return 8;
1242 case DBGFRETURNTYPE_FAR16: return 4;
1243 case DBGFRETURNTYPE_FAR32: return 4;
1244 case DBGFRETURNTYPE_FAR64: return 8;
1245 case DBGFRETURNTYPE_IRET16: return 6;
1246 case DBGFRETURNTYPE_IRET32: return 4*3;
1247 case DBGFRETURNTYPE_IRET32_PRIV: return 4*5;
1248 case DBGFRETURNTYPE_IRET32_V86: return 4*9;
1249 case DBGFRETURNTYPE_IRET64:
1250 default:
1251 return 0;
1252 }
1253}
1254
1255
1256/** Pointer to stack frame info. */
1257typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
1258/**
1259 * Info about a stack frame.
1260 */
1261typedef struct DBGFSTACKFRAME
1262{
1263 /** Frame number. */
1264 RTUINT iFrame;
1265 /** Frame flags. */
1266 RTUINT fFlags;
1267 /** The frame address.
1268 * The off member is [e|r]bp and the Sel member is ss. */
1269 DBGFADDRESS AddrFrame;
1270 /** The stack address of the frame.
1271 * The off member is [e|r]sp and the Sel member is ss. */
1272 DBGFADDRESS AddrStack;
1273 /** The program counter (PC) address of the frame.
1274 * The off member is [e|r]ip and the Sel member is cs. */
1275 DBGFADDRESS AddrPC;
1276 /** Pointer to the symbol nearest the program counter (PC). NULL if not found. */
1277 PDBGFSYMBOL pSymPC;
1278 /** Pointer to the linnumber nearest the program counter (PC). NULL if not found. */
1279 PDBGFLINE pLinePC;
1280
1281 /** The return frame address.
1282 * The off member is [e|r]bp and the Sel member is ss. */
1283 DBGFADDRESS AddrReturnFrame;
1284 /** The return stack address.
1285 * The off member is [e|r]sp and the Sel member is ss. */
1286 DBGFADDRESS AddrReturnStack;
1287 /** The way this frame returns to the next one. */
1288 DBGFRETURNTYPE enmReturnType;
1289
1290 /** The program counter (PC) address which the frame returns to.
1291 * The off member is [e|r]ip and the Sel member is cs. */
1292 DBGFADDRESS AddrReturnPC;
1293 /** Pointer to the symbol nearest the return PC. NULL if not found. */
1294 PDBGFSYMBOL pSymReturnPC;
1295 /** Pointer to the linnumber nearest the return PC. NULL if not found. */
1296 PDBGFLINE pLineReturnPC;
1297
1298 /** 32-bytes of stack arguments. */
1299 union
1300 {
1301 /** 64-bit view */
1302 uint64_t au64[4];
1303 /** 32-bit view */
1304 uint32_t au32[8];
1305 /** 16-bit view */
1306 uint16_t au16[16];
1307 /** 8-bit view */
1308 uint8_t au8[32];
1309 } Args;
1310
1311 /** Pointer to the next frame.
1312 * Might not be used in some cases, so consider it internal. */
1313 PDBGFSTACKFRAME pNext;
1314 /** Pointer to the first frame.
1315 * Might not be used in some cases, so consider it internal. */
1316 PDBGFSTACKFRAME pFirst;
1317} DBGFSTACKFRAME;
1318
1319/** @name DBGFSTACKFRAME Flags.
1320 * @{ */
1321/** Set if the content of the frame is filled in by DBGFR3StackWalk() and can be used
1322 * to construct the next frame. */
1323#define DBGFSTACKFRAME_FLAGS_ALL_VALID BIT(0)
1324/** This is the last stack frame we can read.
1325 * This flag is not set if the walk stop because of max dept or recursion. */
1326#define DBGFSTACKFRAME_FLAGS_LAST BIT(1)
1327/** This is the last record because we detected a loop. */
1328#define DBGFSTACKFRAME_FLAGS_LOOP BIT(2)
1329/** This is the last record because we reached the maximum depth. */
1330#define DBGFSTACKFRAME_FLAGS_MAX_DEPTH BIT(3)
1331/** @} */
1332
1333/**
1334 * Begins a stack walk.
1335 * This will construct and obtain the first frame.
1336 *
1337 * @returns VINF_SUCCESS on success.
1338 * @returns VERR_NO_MEMORY if we're out of memory.
1339 * @param pVM The VM handle.
1340 * @param pFrame The stack frame info structure.
1341 * On input this structure must be memset to zero.
1342 * If wanted, the AddrPC, AddrStack and AddrFrame fields may be set
1343 * to valid addresses after memsetting it. Any of those fields not set
1344 * will be fetched from the guest CPU state.
1345 * On output the structure will contain all the information we were able to
1346 * obtain about the stack frame.
1347 */
1348DBGFR3DECL(int) DBGFR3StackWalkBeginGuest(PVM pVM, PDBGFSTACKFRAME pFrame);
1349
1350/**
1351 * Begins a stack walk.
1352 * This will construct and obtain the first frame.
1353 *
1354 * @returns VINF_SUCCESS on success.
1355 * @returns VERR_NO_MEMORY if we're out of memory.
1356 * @param pVM The VM handle.
1357 * @param pFrame The stack frame info structure.
1358 * On input this structure must be memset to zero.
1359 * If wanted, the AddrPC, AddrStack and AddrFrame fields may be set
1360 * to valid addresses after memsetting it. Any of those fields not set
1361 * will be fetched from the hypervisor CPU state.
1362 * On output the structure will contain all the information we were able to
1363 * obtain about the stack frame.
1364 */
1365DBGFR3DECL(int) DBGFR3StackWalkBeginHyper(PVM pVM, PDBGFSTACKFRAME pFrame);
1366
1367/**
1368 * Gets the next stack frame.
1369 *
1370 * @returns VINF_SUCCESS
1371 * @returns VERR_NO_MORE_FILES if not more stack frames.
1372 * @param pVM The VM handle.
1373 * @param pFrame Pointer to the current frame on input, content is replaced with the next frame on successful return.
1374 */
1375DBGFR3DECL(int) DBGFR3StackWalkNext(PVM pVM, PDBGFSTACKFRAME pFrame);
1376
1377/**
1378 * Ends a stack walk process.
1379 *
1380 * This *must* be called after a successful first call to any of the stack
1381 * walker functions. If not called we will leak memory or other resources.
1382 *
1383 * @param pVM The VM handle.
1384 * @param pFrame The stackframe as returned by the last stack walk call.
1385 */
1386DBGFR3DECL(void) DBGFR3StackWalkEnd(PVM pVM, PDBGFSTACKFRAME pFrame);
1387
1388
1389
1390
1391/** Flags to pass to DBGFR3DisasInstrEx().
1392 * @{ */
1393/** Disassemble the current guest instruction, with annotations. */
1394#define DBGF_DISAS_FLAGS_CURRENT_GUEST BIT(0)
1395/** Disassemble the current hypervisor instruction, with annotations. */
1396#define DBGF_DISAS_FLAGS_CURRENT_HYPER BIT(1)
1397/** No annotations for current context. */
1398#define DBGF_DISAS_FLAGS_NO_ANNOTATION BIT(2)
1399/** No symbol lookup. */
1400#define DBGF_DISAS_FLAGS_NO_SYMBOLS BIT(3)
1401/** No instruction bytes. */
1402#define DBGF_DISAS_FLAGS_NO_BYTES BIT(4)
1403/** No address in the output. */
1404#define DBGF_DISAS_FLAGS_NO_ADDRESS BIT(5)
1405/** @} */
1406
1407/** Special flat selector. */
1408#define DBGF_SEL_FLAT 1
1409
1410/**
1411 * Disassembles the one instruction according to the specified flags and address.
1412 *
1413 * @returns VBox status code.
1414 * @param pVM VM handle.
1415 * @param Sel The code selector. This used to determin the 32/16 bit ness and
1416 * calculation of the actual instruction address.
1417 * Use DBGF_SEL_FLAT for specifying a flat address.
1418 * @param GCPtr The code address relative to the base of Sel.
1419 * @param fFlags Flags controlling where to start and how to format.
1420 * A combination of the DBGF_DISAS_FLAGS_* #defines.
1421 * @param pszOutput Output buffer.
1422 * @param cchOutput Size of the output buffer.
1423 * @param pcbInstr Where to return the size of the instruction.
1424 */
1425DBGFR3DECL(int) DBGFR3DisasInstrEx(PVM pVM, RTSEL Sel, RTGCPTR GCPtr, unsigned fFlags, char *pszOutput, uint32_t cchOutput, uint32_t *pcbInstr);
1426
1427/**
1428 * Disassembles the current instruction.
1429 * Addresses will be tried resolved to symbols
1430 *
1431 * @returns VBox status code.
1432 * @param pVM VM handle.
1433 * @param Sel The code selector. This used to determin the 32/16 bit ness and
1434 * calculation of the actual instruction address.
1435 * Use DBGF_SEL_FLAT for specifying a flat address.
1436 * @param GCPtr The code address relative to the base of Sel.
1437 * @param pszOutput Output buffer.
1438 * @param cbOutput Size of the output buffer.
1439 */
1440DBGFR3DECL(int) DBGFR3DisasInstr(PVM pVM, RTSEL Sel, RTGCPTR GCPtr, char *pszOutput, uint32_t cbOutput);
1441
1442/**
1443 * Disassembles the current instruction.
1444 * All registers and data will be displayed. Addresses will be attempted resolved to symbols
1445 *
1446 * @returns VBox status code.
1447 * @param pVM VM handle.
1448 * @param pszOutput Output buffer.
1449 * @param cbOutput Size of the output buffer.
1450 */
1451DBGFR3DECL(int) DBGFR3DisasInstrCurrent(PVM pVM, char *pszOutput, uint32_t cbOutput);
1452
1453/**
1454 * Disassembles the current guest context instruction and writes it to the log.
1455 * All registers and data will be displayed. Addresses will be attempted resolved to symbols.
1456 *
1457 * @returns VBox status code.
1458 * @param pVM VM handle.
1459 * @param pszPrefix Short prefix string to the dissassembly string. (optional)
1460 */
1461DBGFR3DECL(int) DBGFR3DisasInstrCurrentLogInternal(PVM pVM, const char *pszPrefix);
1462
1463/** @def DBGFR3DisasInstrCurrentLog
1464 * Disassembles the current guest context instruction and writes it to the log.
1465 * All registers and data will be displayed. Addresses will be attempted resolved to symbols.
1466 */
1467#ifdef LOG_ENABLED
1468# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) \
1469 do { \
1470 if (LogIsEnabled()) \
1471 DBGFR3DisasInstrCurrentLogInternal(pVM, pszPrefix); \
1472 } while (0)
1473#else
1474# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) do { } while (0)
1475#endif
1476
1477/**
1478 * Disassembles the specified guest context instruction and writes it to the log.
1479 * Addresses will be attempted resolved to symbols.
1480 *
1481 * @returns VBox status code.
1482 * @param pVM VM handle.
1483 * @param Sel The code selector. This used to determin the 32/16 bit-ness and
1484 * calculation of the actual instruction address.
1485 * @param GCPtr The code address relative to the base of Sel.
1486 */
1487DBGFR3DECL(int) DBGFR3DisasInstrLogInternal(PVM pVM, RTSEL Sel, RTGCPTR GCPtr);
1488
1489/** @def DBGFR3DisasInstrLog
1490 * Disassembles the specified guest context instruction and writes it to the log.
1491 * Addresses will be attempted resolved to symbols.
1492 */
1493#ifdef LOG_ENABLED
1494# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) \
1495 do { \
1496 if (LogIsEnabled()) \
1497 DBGFR3DisasInstrLogInternal(pVM, Sel, GCPtr); \
1498 } while (0)
1499#else
1500# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) do { } while (0)
1501#endif
1502
1503/** @} */
1504
1505__END_DECLS
1506
1507#endif
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