dbgf.h@ 29567

Last change on this file since 29567 was 28800, checked in by vboxsync, 15 years ago
Automated rebranding to Oracle copyright/license strings via filemuncher
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 38.8 KB

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

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

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

Download in other formats: