dbgf.h@ 19239

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

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

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

Download in other formats: