dbgf.h@ 9721

Last change on this file since 9721 was 9387, checked in by vboxsync, 17 years ago
64-bit GC alignment fixes
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 55.6 KB

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

Note: See TracBrowser for help on using the repository browser.

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

Download in other formats: