dbgf.h@ 19288

Last change on this file since 19288 was 19288, checked in by vboxsync, 16 years ago
DBGF,TRPM,HWACCM: Merged DBGFR0.cpp and DBGFGC.cpp into VMMRZ/DBGFRZ.cpp (new directory for things that are common to both R0 and RC).
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 33.5 KB

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

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

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

Download in other formats: