dbgf.h@ 28025

Last change on this file since 28025 was 26112, checked in by vboxsync, 15 years ago
PDM,UsbMsd,++: Resumed hacking the MSD code.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 39.0 KB

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

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

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

Download in other formats: