dbgf.h@ 19333

Last change on this file since 19333 was 19293, checked in by vboxsync, 16 years ago
DBGF,VMM: SMP refactoring of the DBGF disassembler code. Changed VMMGetCpu and VMMGetCpuId to return NULL and NIL if the caller isn't an EMT. Renamed VMMGetCpuEx to VMMGetCpuById.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 34.4 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 end of the valid return types. */
629	DBGFRETURNTYPE_END,
630	/** The usual 32-bit blowup. */
631	DBGFRETURNTYPE_32BIT_HACK = 0x7fffffff
632	} DBGFRETURNTYPE;
633
634	/**
635	* Figures the size of the return state on the stack.
636	*
637	* @returns number of bytes. 0 if invalid parameter.
638	* @param enmRetType The type of return.
639	*/
640	DECLINLINE(unsigned) DBGFReturnTypeSize(DBGFRETURNTYPE enmRetType)
641	{
642	switch (enmRetType)
643	{
644	case DBGFRETURNTYPE_NEAR16: return 2;
645	case DBGFRETURNTYPE_NEAR32: return 4;
646	case DBGFRETURNTYPE_NEAR64: return 8;
647	case DBGFRETURNTYPE_FAR16: return 4;
648	case DBGFRETURNTYPE_FAR32: return 4;
649	case DBGFRETURNTYPE_FAR64: return 8;
650	case DBGFRETURNTYPE_IRET16: return 6;
651	case DBGFRETURNTYPE_IRET32: return 4*3;
652	case DBGFRETURNTYPE_IRET32_PRIV: return 4*5;
653	case DBGFRETURNTYPE_IRET32_V86: return 4*9;
654	case DBGFRETURNTYPE_IRET64:
655	default:
656	return 0;
657	}
658	}
659
660
661	/** Pointer to stack frame info. */
662	typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
663	/** Pointer to const stack frame info. */
664	typedef struct DBGFSTACKFRAME const *PCDBGFSTACKFRAME;
665	/**
666	* Info about a stack frame.
667	*/
668	typedef struct DBGFSTACKFRAME
669	{
670	/** Frame number. */
671	RTUINT iFrame;
672	/** Frame flags. */
673	RTUINT fFlags;
674	/** The frame address.
675	* The off member is [e\|r]bp and the Sel member is ss. */
676	DBGFADDRESS AddrFrame;
677	/** The stack address of the frame.
678	* The off member is [e\|r]sp and the Sel member is ss. */
679	DBGFADDRESS AddrStack;
680	/** The program counter (PC) address of the frame.
681	* The off member is [e\|r]ip and the Sel member is cs. */
682	DBGFADDRESS AddrPC;
683	/** Pointer to the symbol nearest the program counter (PC). NULL if not found. */
684	PDBGFSYMBOL pSymPC;
685	/** Pointer to the linnumber nearest the program counter (PC). NULL if not found. */
686	PDBGFLINE pLinePC;
687
688	/** The return frame address.
689	* The off member is [e\|r]bp and the Sel member is ss. */
690	DBGFADDRESS AddrReturnFrame;
691	/** The return stack address.
692	* The off member is [e\|r]sp and the Sel member is ss. */
693	DBGFADDRESS AddrReturnStack;
694	/** The way this frame returns to the next one. */
695	DBGFRETURNTYPE enmReturnType;
696
697	/** The program counter (PC) address which the frame returns to.
698	* The off member is [e\|r]ip and the Sel member is cs. */
699	DBGFADDRESS AddrReturnPC;
700	/** Pointer to the symbol nearest the return PC. NULL if not found. */
701	PDBGFSYMBOL pSymReturnPC;
702	/** Pointer to the linnumber nearest the return PC. NULL if not found. */
703	PDBGFLINE pLineReturnPC;
704
705	/** 32-bytes of stack arguments. */
706	union
707	{
708	/** 64-bit view */
709	uint64_t au64[4];
710	/** 32-bit view */
711	uint32_t au32[8];
712	/** 16-bit view */
713	uint16_t au16[16];
714	/** 8-bit view */
715	uint8_t au8[32];
716	} Args;
717
718	/** Pointer to the next frame.
719	* Might not be used in some cases, so consider it internal. */
720	PCDBGFSTACKFRAME pNextInternal;
721	/** Pointer to the first frame.
722	* Might not be used in some cases, so consider it internal. */
723	PCDBGFSTACKFRAME pFirstInternal;
724	} DBGFSTACKFRAME;
725
726	/** @name DBGFSTACKFRAME Flags.
727	* @{ */
728	/** Set if the content of the frame is filled in by DBGFR3StackWalk() and can be used
729	* to construct the next frame. */
730	#define DBGFSTACKFRAME_FLAGS_ALL_VALID RT_BIT(0)
731	/** This is the last stack frame we can read.
732	* This flag is not set if the walk stop because of max dept or recursion. */
733	#define DBGFSTACKFRAME_FLAGS_LAST RT_BIT(1)
734	/** This is the last record because we detected a loop. */
735	#define DBGFSTACKFRAME_FLAGS_LOOP RT_BIT(2)
736	/** This is the last record because we reached the maximum depth. */
737	#define DBGFSTACKFRAME_FLAGS_MAX_DEPTH RT_BIT(3)
738	/** @} */
739
740	VMMR3DECL(int) DBGFR3StackWalkBeginGuest(PVM pVM, VMCPUID idCpu, PCDBGFSTACKFRAME *ppFirstFrame);
741	VMMR3DECL(int) DBGFR3StackWalkBeginHyper(PVM pVM, VMCPUID idCpu, PCDBGFSTACKFRAME *ppFirstFrame);
742	VMMR3DECL(int) DBGFR3StackWalkBeginGuestEx(PVM pVM, VMCPUID idCpu, PCDBGFADDRESS pAddrFrame,
743	PCDBGFADDRESS pAddrStack,PCDBGFADDRESS pAddrPC,
744	DBGFRETURNTYPE enmReturnType, PCDBGFSTACKFRAME *ppFirstFrame);
745	VMMR3DECL(int) DBGFR3StackWalkBeginHyperEx(PVM pVM, VMCPUID idCpu, PCDBGFADDRESS pAddrFrame,
746	PCDBGFADDRESS pAddrStack,PCDBGFADDRESS pAddrPC,
747	DBGFRETURNTYPE enmReturnType, PCDBGFSTACKFRAME *ppFirstFrame);
748	VMMR3DECL(PCDBGFSTACKFRAME) DBGFR3StackWalkNext(PCDBGFSTACKFRAME pCurrent);
749	VMMR3DECL(void) DBGFR3StackWalkEnd(PCDBGFSTACKFRAME pFirstFrame);
750
751
752
753
754	/** Flags to pass to DBGFR3DisasInstrEx().
755	* @{ */
756	/** Disassemble the current guest instruction, with annotations. */
757	#define DBGF_DISAS_FLAGS_CURRENT_GUEST RT_BIT(0)
758	/** Disassemble the current hypervisor instruction, with annotations. */
759	#define DBGF_DISAS_FLAGS_CURRENT_HYPER RT_BIT(1)
760	/** No annotations for current context. */
761	#define DBGF_DISAS_FLAGS_NO_ANNOTATION RT_BIT(2)
762	/** No symbol lookup. */
763	#define DBGF_DISAS_FLAGS_NO_SYMBOLS RT_BIT(3)
764	/** No instruction bytes. */
765	#define DBGF_DISAS_FLAGS_NO_BYTES RT_BIT(4)
766	/** No address in the output. */
767	#define DBGF_DISAS_FLAGS_NO_ADDRESS RT_BIT(5)
768	/** @} */
769
770	/** Special flat selector. */
771	#define DBGF_SEL_FLAT 1
772
773	VMMR3DECL(int) DBGFR3DisasInstrEx(PVM pVM, VMCPUID idCpu, RTSEL Sel, RTGCPTR GCPtr, unsigned fFlags, char pszOutput, uint32_t cchOutput, uint32_t pcbInstr);
774	VMMR3DECL(int) DBGFR3DisasInstrCurrent(PVM pVM, char *pszOutput, uint32_t cbOutput);
775	VMMR3DECL(int) DBGFR3DisasInstrCurrentLogInternal(PVM pVM, const char *pszPrefix);
776
777	/** @def DBGFR3DisasInstrCurrentLog
778	* Disassembles the current guest context instruction and writes it to the log.
779	* All registers and data will be displayed. Addresses will be attempted resolved to symbols.
780	*/
781	/** @todo SMP */
782	#ifdef LOG_ENABLED
783	# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) \
784	do { \
785	if (LogIsEnabled()) \
786	DBGFR3DisasInstrCurrentLogInternal(pVM, pszPrefix); \
787	} while (0)
788	#else
789	# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) do { } while (0)
790	#endif
791
792	VMMR3DECL(int) DBGFR3DisasInstrLogInternal(PVM pVM, RTSEL Sel, RTGCPTR GCPtr);
793
794	/** @def DBGFR3DisasInstrLog
795	* Disassembles the specified guest context instruction and writes it to the log.
796	* Addresses will be attempted resolved to symbols.
797	* @thread Any EMT.
798	*/
799	#ifdef LOG_ENABLED
800	# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) \
801	do { \
802	if (LogIsEnabled()) \
803	DBGFR3DisasInstrLogInternal(pVM, Sel, GCPtr); \
804	} while (0)
805	#else
806	# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) do { } while (0)
807	#endif
808
809
810	VMMR3DECL(int) DBGFR3MemScan(PVM pVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, RTGCUINTPTR cbRange, const uint8_t *pabNeedle, size_t cbNeedle, PDBGFADDRESS pHitAddress);
811	VMMR3DECL(int) DBGFR3MemRead(PVM pVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void *pvBuf, size_t cbRead);
812	VMMR3DECL(int) DBGFR3MemReadString(PVM pVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, char *pszBuf, size_t cbBuf);
813	VMMR3DECL(int) DBGFR3MemWrite(PVM pVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void const *pvBuf, size_t cbRead);
814
815
816	/**
817	* Guest OS digger interface identifier.
818	*
819	* This is for use together with PDBGFR3QueryInterface and is used to
820	* obtain access to optional interfaces.
821	*/
822	typedef enum DBGFOSINTERFACE
823	{
824	/** The usual invalid entry. */
825	DBGFOSINTERFACE_INVALID = 0,
826	/** Process info. */
827	DBGFOSINTERFACE_PROCESS,
828	/** Thread info. */
829	DBGFOSINTERFACE_THREAD,
830	/** The end of the valid entries. */
831	DBGFOSINTERFACE_END,
832	/** The usual 32-bit type blowup. */
833	DBGFOSINTERFACE_32BIT_HACK = 0x7fffffff
834	} DBGFOSINTERFACE;
835	/** Pointer to a Guest OS digger interface identifier. */
836	typedef DBGFOSINTERFACE *PDBGFOSINTERFACE;
837	/** Pointer to a const Guest OS digger interface identifier. */
838	typedef DBGFOSINTERFACE const *PCDBGFOSINTERFACE;
839
840
841	/**
842	* Guest OS Digger Registration Record.
843	*
844	* This is used with the DBGFR3OSRegister() API.
845	*/
846	typedef struct DBGFOSREG
847	{
848	/** Magic value (DBGFOSREG_MAGIC). */
849	uint32_t u32Magic;
850	/** Flags. Reserved. */
851	uint32_t fFlags;
852	/** The size of the instance data. */
853	uint32_t cbData;
854	/** Operative System name. */
855	char szName[24];
856
857	/**
858	* Constructs the instance.
859	*
860	* @returns VBox status code.
861	* @param pVM Pointer to the shared VM structure.
862	* @param pvData Pointer to the instance data.
863	*/
864	DECLCALLBACKMEMBER(int, pfnConstruct)(PVM pVM, void *pvData);
865
866	/**
867	* Destroys the instance.
868	*
869	* @param pVM Pointer to the shared VM structure.
870	* @param pvData Pointer to the instance data.
871	*/
872	DECLCALLBACKMEMBER(void, pfnDestruct)(PVM pVM, void *pvData);
873
874	/**
875	* Probes the guest memory for OS finger prints.
876	*
877	* No setup or so is performed, it will be followed by a call to pfnInit
878	* or pfnRefresh that should take care of that.
879	*
880	* @returns true if is an OS handled by this module, otherwise false.
881	* @param pVM Pointer to the shared VM structure.
882	* @param pvData Pointer to the instance data.
883	*/
884	DECLCALLBACKMEMBER(bool, pfnProbe)(PVM pVM, void *pvData);
885
886	/**
887	* Initializes a fresly detected guest, loading symbols and such useful stuff.
888	*
889	* This is called after pfnProbe.
890	*
891	* @returns VBox status code.
892	* @param pVM Pointer to the shared VM structure.
893	* @param pvData Pointer to the instance data.
894	*/
895	DECLCALLBACKMEMBER(int, pfnInit)(PVM pVM, void *pvData);
896
897	/**
898	* Refreshes symbols and stuff following a redetection of the same OS.
899	*
900	* This is called after pfnProbe.
901	*
902	* @returns VBox status code.
903	* @param pVM Pointer to the shared VM structure.
904	* @param pvData Pointer to the instance data.
905	*/
906	DECLCALLBACKMEMBER(int, pfnRefresh)(PVM pVM, void *pvData);
907
908	/**
909	* Terminates an OS when a new (or none) OS has been detected,
910	* and before destruction.
911	*
912	* This is called after pfnProbe and if needed before pfnDestruct.
913	*
914	* @param pVM Pointer to the shared VM structure.
915	* @param pvData Pointer to the instance data.
916	*/
917	DECLCALLBACKMEMBER(void, pfnTerm)(PVM pVM, void *pvData);
918
919	/**
920	* Queries the version of the running OS.
921	*
922	* This is only called after pfnInit().
923	*
924	* @returns VBox status code.
925	* @param pVM Pointer to the shared VM structure.
926	* @param pvData Pointer to the instance data.
927	* @param pszVersion Where to store the version string.
928	* @param cchVersion The size of the version string buffer.
929	*/
930	DECLCALLBACKMEMBER(int, pfnQueryVersion)(PVM pVM, void pvData, char pszVersion, size_t cchVersion);
931
932	/**
933	* Queries the pointer to a interface.
934	*
935	* This is called after pfnProbe.
936	*
937	* @returns Pointer to the interface if available, NULL if not available.
938	* @param pVM Pointer to the shared VM structure.
939	* @param pvData Pointer to the instance data.
940	* @param enmIf The interface identifier.
941	*/
942	DECLCALLBACKMEMBER(void , pfnQueryInterface)(PVM pVM, void pvData, DBGFOSINTERFACE enmIf);
943
944	/** Trailing magic (DBGFOSREG_MAGIC). */
945	uint32_t u32EndMagic;
946	} DBGFOSREG;
947	/** Pointer to a Guest OS digger registration record. */
948	typedef DBGFOSREG *PDBGFOSREG;
949	/** Pointer to a const Guest OS digger registration record. */
950	typedef DBGFOSREG const *PCDBGFOSREG;
951
952	/** Magic value for DBGFOSREG::u32Magic and DBGFOSREG::u32EndMagic. (Hitomi Kanehara) */
953	#define DBGFOSREG_MAGIC 0x19830808
954
955	VMMR3DECL(int) DBGFR3OSRegister(PVM pVM, PCDBGFOSREG pReg);
956	VMMR3DECL(int) DBGFR3OSDeregister(PVM pVM, PCDBGFOSREG pReg);
957	VMMR3DECL(int) DBGFR3OSDetect(PVM pVM, char *pszName, size_t cchName);
958	VMMR3DECL(int) DBGFR3OSQueryNameAndVersion(PVM pVM, char pszName, size_t cchName, char pszVersion, size_t cchVersion);
959	VMMR3DECL(void *) DBGFR3OSQueryInterface(PVM pVM, DBGFOSINTERFACE enmIf);
960
961	/** @} */
962
963
964	__END_DECLS
965
966	#endif
967

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

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

Download in other formats: