dbgf.h@ 47036

Last change on this file since 47036 was 46217, checked in by vboxsync, 12 years ago
Fixed the 'r', 'rg' and 'rg32' commands in 64-bit guest code.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 61.8 KB

Line
1	/** @file
2	* DBGF - Debugger Facility.
3	*/
4
5	/*
6	* Copyright (C) 2006-2013 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef ___VBox_vmm_dbgf_h
27	#define ___VBox_vmm_dbgf_h
28
29	#include <VBox/types.h>
30	#include <VBox/log.h> /* LOG_ENABLED */
31	#include <VBox/vmm/vmm.h>
32	#include <VBox/vmm/dbgfsel.h>
33
34	#include <iprt/stdarg.h>
35	#include <iprt/dbg.h>
36
37	RT_C_DECLS_BEGIN
38
39
40	/** @defgroup grp_dbgf The Debugger Facility API
41	* @{
42	*/
43
44	#if defined(IN_RC) \|\| defined(IN_RING0)
45	/** @addgroup grp_dbgf_rz The RZ DBGF API
46	* @ingroup grp_dbgf
47	* @{
48	*/
49	VMMRZ_INT_DECL(int) DBGFRZTrap01Handler(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame, RTGCUINTREG uDr6);
50	VMMRZ_INT_DECL(int) DBGFRZTrap03Handler(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame);
51	/** @} */
52	#endif
53
54
55
56	#ifdef IN_RING3
57
58	/**
59	* Mixed address.
60	*/
61	typedef struct DBGFADDRESS
62	{
63	/** The flat address. */
64	RTGCUINTPTR FlatPtr;
65	/** The selector offset address. */
66	RTGCUINTPTR off;
67	/** The selector. DBGF_SEL_FLAT is a legal value. */
68	RTSEL Sel;
69	/** Flags describing further details about the address. */
70	uint16_t fFlags;
71	} DBGFADDRESS;
72	/** Pointer to a mixed address. */
73	typedef DBGFADDRESS *PDBGFADDRESS;
74	/** Pointer to a const mixed address. */
75	typedef const DBGFADDRESS *PCDBGFADDRESS;
76
77	/** @name DBGFADDRESS Flags.
78	* @{ */
79	/** A 16:16 far address. */
80	#define DBGFADDRESS_FLAGS_FAR16 0
81	/** A 16:32 far address. */
82	#define DBGFADDRESS_FLAGS_FAR32 1
83	/** A 16:64 far address. */
84	#define DBGFADDRESS_FLAGS_FAR64 2
85	/** A flat address. */
86	#define DBGFADDRESS_FLAGS_FLAT 3
87	/** A physical address. */
88	#define DBGFADDRESS_FLAGS_PHYS 4
89	/** A physical address. */
90	#define DBGFADDRESS_FLAGS_RING0 5
91	/** The address type mask. */
92	#define DBGFADDRESS_FLAGS_TYPE_MASK 7
93
94	/** Set if the address is valid. */
95	#define DBGFADDRESS_FLAGS_VALID RT_BIT(3)
96
97	/** The address is within the hypervisor memoary area (HMA).
98	* If not set, the address can be assumed to be a guest address. */
99	#define DBGFADDRESS_FLAGS_HMA RT_BIT(4)
100
101	/** Checks if the mixed address is flat or not. */
102	#define DBGFADDRESS_IS_FLAT(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FLAT )
103	/** Checks if the mixed address is flat or not. */
104	#define DBGFADDRESS_IS_PHYS(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_PHYS )
105	/** Checks if the mixed address is far 16:16 or not. */
106	#define DBGFADDRESS_IS_FAR16(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR16 )
107	/** Checks if the mixed address is far 16:32 or not. */
108	#define DBGFADDRESS_IS_FAR32(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR32 )
109	/** Checks if the mixed address is far 16:64 or not. */
110	#define DBGFADDRESS_IS_FAR64(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR64 )
111	/** Checks if the mixed address is valid. */
112	#define DBGFADDRESS_IS_VALID(pAddress) ( !!((pAddress)->fFlags & DBGFADDRESS_FLAGS_VALID) )
113	/** Checks if the address is flagged as within the HMA. */
114	#define DBGFADDRESS_IS_HMA(pAddress) ( !!((pAddress)->fFlags & DBGFADDRESS_FLAGS_HMA) )
115	/** @} */
116
117	VMMR3DECL(int) DBGFR3AddrFromSelOff(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, RTSEL Sel, RTUINTPTR off);
118	VMMR3DECL(int) DBGFR3AddrFromSelInfoOff(PUVM pUVM, PDBGFADDRESS pAddress, PCDBGFSELINFO pSelInfo, RTUINTPTR off);
119	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromFlat(PUVM pUVM, PDBGFADDRESS pAddress, RTGCUINTPTR FlatPtr);
120	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromPhys(PUVM pUVM, PDBGFADDRESS pAddress, RTGCPHYS PhysAddr);
121	VMMR3DECL(bool) DBGFR3AddrIsValid(PUVM pUVM, PCDBGFADDRESS pAddress);
122	VMMR3DECL(int) DBGFR3AddrToPhys(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, PRTGCPHYS pGCPhys);
123	VMMR3DECL(int) DBGFR3AddrToHostPhys(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, PRTHCPHYS pHCPhys);
124	VMMR3DECL(int) DBGFR3AddrToVolatileR3Ptr(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, bool fReadOnly, void **ppvR3Ptr);
125	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrAdd(PDBGFADDRESS pAddress, RTGCUINTPTR uAddend);
126	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrSub(PDBGFADDRESS pAddress, RTGCUINTPTR uSubtrahend);
127
128	#endif /* IN_RING3 */
129
130
131
132	/**
133	* VMM Debug Event Type.
134	*/
135	typedef enum DBGFEVENTTYPE
136	{
137	/** Halt completed.
138	* This notifies that a halt command have been successfully completed.
139	*/
140	DBGFEVENT_HALT_DONE = 0,
141	/** Detach completed.
142	* This notifies that the detach command have been successfully completed.
143	*/
144	DBGFEVENT_DETACH_DONE,
145	/** The command from the debugger is not recognized.
146	* This means internal error or half implemented features.
147	*/
148	DBGFEVENT_INVALID_COMMAND,
149
150
151	/** Fatal error.
152	* This notifies a fatal error in the VMM and that the debugger get's a
153	* chance to first hand information about the the problem.
154	*/
155	DBGFEVENT_FATAL_ERROR = 100,
156	/** Breakpoint Hit.
157	* This notifies that a breakpoint installed by the debugger was hit. The
158	* identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
159	*/
160	DBGFEVENT_BREAKPOINT,
161	/** Breakpoint Hit in the Hypervisor.
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_HYPER,
166	/** Assertion in the Hypervisor (breakpoint instruction).
167	* This notifies that a breakpoint instruction was hit in the hypervisor context.
168	*/
169	DBGFEVENT_ASSERTION_HYPER,
170	/** Single Stepped.
171	* This notifies that a single step operation was completed.
172	*/
173	DBGFEVENT_STEPPED,
174	/** Single Stepped.
175	* This notifies that a hypervisor single step operation was completed.
176	*/
177	DBGFEVENT_STEPPED_HYPER,
178	/** The developer have used the DBGFSTOP macro or the PDMDeviceDBGFSTOP function
179	* to bring up the debugger at a specific place.
180	*/
181	DBGFEVENT_DEV_STOP,
182	/** The VM is powering off.
183	* When this notification is received, the debugger thread should detach ASAP.
184	*/
185	DBGFEVENT_POWERING_OFF,
186
187	/** The usual 32-bit hack. */
188	DBGFEVENT_32BIT_HACK = 0x7fffffff
189	} DBGFEVENTTYPE;
190
191
192	/**
193	* The context of an event.
194	*/
195	typedef enum DBGFEVENTCTX
196	{
197	/** The usual invalid entry. */
198	DBGFEVENTCTX_INVALID = 0,
199	/** Raw mode. */
200	DBGFEVENTCTX_RAW,
201	/** Recompiled mode. */
202	DBGFEVENTCTX_REM,
203	/** VMX / AVT mode. */
204	DBGFEVENTCTX_HM,
205	/** Hypervisor context. */
206	DBGFEVENTCTX_HYPER,
207	/** Other mode */
208	DBGFEVENTCTX_OTHER,
209
210	/** The usual 32-bit hack */
211	DBGFEVENTCTX_32BIT_HACK = 0x7fffffff
212	} DBGFEVENTCTX;
213
214	/**
215	* VMM Debug Event.
216	*/
217	typedef struct DBGFEVENT
218	{
219	/** Type. */
220	DBGFEVENTTYPE enmType;
221	/** Context */
222	DBGFEVENTCTX enmCtx;
223	/** Type specific data. */
224	union
225	{
226	/** Fatal error details. */
227	struct
228	{
229	/** The GC return code. */
230	int rc;
231	} FatalError;
232
233	/** Source location. */
234	struct
235	{
236	/** File name. */
237	R3PTRTYPE(const char *) pszFile;
238	/** Function name. */
239	R3PTRTYPE(const char *) pszFunction;
240	/** Message. */
241	R3PTRTYPE(const char *) pszMessage;
242	/** Line number. */
243	unsigned uLine;
244	} Src;
245
246	/** Assertion messages. */
247	struct
248	{
249	/** The first message. */
250	R3PTRTYPE(const char *) pszMsg1;
251	/** The second message. */
252	R3PTRTYPE(const char *) pszMsg2;
253	} Assert;
254
255	/** Breakpoint. */
256	struct DBGFEVENTBP
257	{
258	/** The identifier of the breakpoint which was hit. */
259	RTUINT iBp;
260	} Bp;
261	/** Padding for ensuring that the structure is 8 byte aligned. */
262	uint64_t au64Padding[4];
263	} u;
264	} DBGFEVENT;
265	/** Pointer to VMM Debug Event. */
266	typedef DBGFEVENT *PDBGFEVENT;
267	/** Pointer to const VMM Debug Event. */
268	typedef const DBGFEVENT *PCDBGFEVENT;
269
270	#ifdef IN_RING3 /* The event API only works in ring-3. */
271
272	/** @def DBGFSTOP
273	* Stops the debugger raising a DBGFEVENT_DEVELOPER_STOP event.
274	*
275	* @returns VBox status code which must be propagated up to EM if not VINF_SUCCESS.
276	* @param pVM VM Handle.
277	*/
278	# ifdef VBOX_STRICT
279	# define DBGFSTOP(pVM) DBGFR3EventSrc(pVM, DBGFEVENT_DEV_STOP, __FILE__, __LINE__, __PRETTY_FUNCTION__, NULL)
280	# else
281	# define DBGFSTOP(pVM) VINF_SUCCESS
282	# endif
283
284	VMMR3_INT_DECL(int) DBGFR3Init(PVM pVM);
285	VMMR3_INT_DECL(int) DBGFR3Term(PVM pVM);
286	VMMR3_INT_DECL(void) DBGFR3PowerOff(PVM pVM);
287	VMMR3_INT_DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta);
288	VMMR3_INT_DECL(int) DBGFR3VMMForcedAction(PVM pVM);
289	VMMR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent);
290	VMMR3DECL(int) DBGFR3EventSrc(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine,
291	const char pszFunction, const char pszFormat, ...);
292	VMMR3DECL(int) DBGFR3EventSrcV(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine,
293	const char pszFunction, const char pszFormat, va_list args);
294	VMMR3_INT_DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszMsg1, const char pszMsg2);
295	VMMR3_INT_DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent);
296	VMMR3_INT_DECL(int) DBGFR3PrgStep(PVMCPU pVCpu);
297
298	VMMR3DECL(int) DBGFR3Attach(PUVM pUVM);
299	VMMR3DECL(int) DBGFR3Detach(PUVM pUVM);
300	VMMR3DECL(int) DBGFR3EventWait(PUVM pUVM, RTMSINTERVAL cMillies, PCDBGFEVENT *ppEvent);
301	VMMR3DECL(int) DBGFR3Halt(PUVM pUVM);
302	VMMR3DECL(bool) DBGFR3IsHalted(PUVM pUVM);
303	VMMR3DECL(int) DBGFR3QueryWaitable(PUVM pUVM);
304	VMMR3DECL(int) DBGFR3Resume(PUVM pUVM);
305	VMMR3DECL(int) DBGFR3Step(PUVM pUVM, VMCPUID idCpu);
306	VMMR3DECL(int) DBGFR3InjectNMI(PUVM pUVM, VMCPUID idCpu);
307
308	#endif /* IN_RING3 */
309
310
311
312	/** Breakpoint type. */
313	typedef enum DBGFBPTYPE
314	{
315	/** Free breakpoint entry. */
316	DBGFBPTYPE_FREE = 0,
317	/** Debug register. */
318	DBGFBPTYPE_REG,
319	/** INT 3 instruction. */
320	DBGFBPTYPE_INT3,
321	/** Recompiler. */
322	DBGFBPTYPE_REM,
323	/** ensure 32-bit size. */
324	DBGFBPTYPE_32BIT_HACK = 0x7fffffff
325	} DBGFBPTYPE;
326
327
328	/**
329	* A Breakpoint.
330	*/
331	typedef struct DBGFBP
332	{
333	/** The number of breakpoint hits. */
334	uint64_t cHits;
335	/** The hit number which starts to trigger the breakpoint. */
336	uint64_t iHitTrigger;
337	/** The hit number which stops triggering the breakpoint (disables it).
338	* Use ~(uint64_t)0 if it should never stop. */
339	uint64_t iHitDisable;
340	/** The Flat GC address of the breakpoint.
341	* (PC register value if REM type?) */
342	RTGCUINTPTR GCPtr;
343	/** The breakpoint id. */
344	uint32_t iBp;
345	/** The breakpoint status - enabled or disabled. */
346	bool fEnabled;
347
348	/** The breakpoint type. */
349	DBGFBPTYPE enmType;
350
351	#if GC_ARCH_BITS == 64
352	uint32_t u32Padding;
353	#endif
354
355	/** Union of type specific data. */
356	union
357	{
358	/** Debug register data. */
359	struct DBGFBPREG
360	{
361	/** The debug register number. */
362	uint8_t iReg;
363	/** The access type (one of the X86_DR7_RW_* value). */
364	uint8_t fType;
365	/** The access size. */
366	uint8_t cb;
367	} Reg;
368	/** Recompiler breakpoint data. */
369	struct DBGFBPINT3
370	{
371	/** The byte value we replaced by the INT 3 instruction. */
372	uint8_t bOrg;
373	} Int3;
374
375	/** Recompiler breakpoint data. */
376	struct DBGFBPREM
377	{
378	/** nothing yet */
379	uint8_t fDummy;
380	} Rem;
381	/** Paddind to ensure that the size is identical on win32 and linux. */
382	uint64_t u64Padding;
383	} u;
384	} DBGFBP;
385
386	/** Pointer to a breakpoint. */
387	typedef DBGFBP *PDBGFBP;
388	/** Pointer to a const breakpoint. */
389	typedef const DBGFBP *PCDBGFBP;
390
391	#ifdef IN_RING3 /* The breakpoint management API is only available in ring-3. */
392	VMMR3DECL(int) DBGFR3BpSet(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, uint32_t *piBp);
393	VMMR3DECL(int) DBGFR3BpSetReg(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable,
394	uint8_t fType, uint8_t cb, uint32_t *piBp);
395	VMMR3DECL(int) DBGFR3BpSetREM(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, uint32_t *piBp);
396	VMMR3DECL(int) DBGFR3BpClear(PUVM pUVM, uint32_t iBp);
397	VMMR3DECL(int) DBGFR3BpEnable(PUVM pUVM, uint32_t iBp);
398	VMMR3DECL(int) DBGFR3BpDisable(PUVM pUVM, uint32_t iBp);
399
400	/**
401	* Breakpoint enumeration callback function.
402	*
403	* @returns VBox status code. Any failure will stop the enumeration.
404	* @param pUVM The user mode VM handle.
405	* @param pvUser The user argument.
406	* @param pBp Pointer to the breakpoint information. (readonly)
407	*/
408	typedef DECLCALLBACK(int) FNDBGFBPENUM(PUVM pUVM, void *pvUser, PCDBGFBP pBp);
409	/** Pointer to a breakpoint enumeration callback function. */
410	typedef FNDBGFBPENUM *PFNDBGFBPENUM;
411
412	VMMR3DECL(int) DBGFR3BpEnum(PUVM pUVM, PFNDBGFBPENUM pfnCallback, void *pvUser);
413	#endif /* IN_RING3 */
414
415	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR7(PVM pVM);
416	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR0(PVM pVM);
417	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR1(PVM pVM);
418	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR2(PVM pVM);
419	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR3(PVM pVM);
420	VMM_INT_DECL(bool) DBGFIsStepping(PVMCPU pVCpu);
421
422
423	#ifdef IN_RING3 /* The CPU mode API only works in ring-3. */
424	VMMR3DECL(CPUMMODE) DBGFR3CpuGetMode(PUVM pUVM, VMCPUID idCpu);
425	VMMR3DECL(VMCPUID) DBGFR3CpuGetCount(PUVM pUVM);
426	VMMR3DECL(bool) DBGFR3CpuIsIn64BitCode(PUVM pUVM, VMCPUID idCpu);
427	#endif
428
429
430
431	#ifdef IN_RING3 /* The info callbacks API only works in ring-3. */
432
433	/**
434	* Info helper callback structure.
435	*/
436	typedef struct DBGFINFOHLP
437	{
438	/**
439	* Print formatted string.
440	*
441	* @param pHlp Pointer to this structure.
442	* @param pszFormat The format string.
443	* @param ... Arguments.
444	*/
445	DECLCALLBACKMEMBER(void, pfnPrintf)(PCDBGFINFOHLP pHlp, const char *pszFormat, ...);
446
447	/**
448	* Print formatted string.
449	*
450	* @param pHlp Pointer to this structure.
451	* @param pszFormat The format string.
452	* @param args Argument list.
453	*/
454	DECLCALLBACKMEMBER(void, pfnPrintfV)(PCDBGFINFOHLP pHlp, const char *pszFormat, va_list args);
455	} DBGFINFOHLP;
456
457
458	/**
459	* Info handler, device version.
460	*
461	* @param pDevIns The device instance which registered the info.
462	* @param pHlp Callback functions for doing output.
463	* @param pszArgs Argument string. Optional and specific to the handler.
464	*/
465	typedef DECLCALLBACK(void) FNDBGFHANDLERDEV(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
466	/** Pointer to a FNDBGFHANDLERDEV function. */
467	typedef FNDBGFHANDLERDEV *PFNDBGFHANDLERDEV;
468
469	/**
470	* Info handler, USB device version.
471	*
472	* @param pUsbIns The USB device instance which registered the info.
473	* @param pHlp Callback functions for doing output.
474	* @param pszArgs Argument string. Optional and specific to the handler.
475	*/
476	typedef DECLCALLBACK(void) FNDBGFHANDLERUSB(PPDMUSBINS pUsbIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
477	/** Pointer to a FNDBGFHANDLERUSB function. */
478	typedef FNDBGFHANDLERUSB *PFNDBGFHANDLERUSB;
479
480	/**
481	* Info handler, driver version.
482	*
483	* @param pDrvIns The driver instance which registered the info.
484	* @param pHlp Callback functions for doing output.
485	* @param pszArgs Argument string. Optional and specific to the handler.
486	*/
487	typedef DECLCALLBACK(void) FNDBGFHANDLERDRV(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
488	/** Pointer to a FNDBGFHANDLERDRV function. */
489	typedef FNDBGFHANDLERDRV *PFNDBGFHANDLERDRV;
490
491	/**
492	* Info handler, internal version.
493	*
494	* @param pVM The VM handle.
495	* @param pHlp Callback functions for doing output.
496	* @param pszArgs Argument string. Optional and specific to the handler.
497	*/
498	typedef DECLCALLBACK(void) FNDBGFHANDLERINT(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs);
499	/** Pointer to a FNDBGFHANDLERINT function. */
500	typedef FNDBGFHANDLERINT *PFNDBGFHANDLERINT;
501
502	/**
503	* Info handler, external version.
504	*
505	* @param pvUser User argument.
506	* @param pHlp Callback functions for doing output.
507	* @param pszArgs Argument string. Optional and specific to the handler.
508	*/
509	typedef DECLCALLBACK(void) FNDBGFHANDLEREXT(void pvUser, PCDBGFINFOHLP pHlp, const char pszArgs);
510	/** Pointer to a FNDBGFHANDLEREXT function. */
511	typedef FNDBGFHANDLEREXT *PFNDBGFHANDLEREXT;
512
513
514	/** @name Flags for the info registration functions.
515	* @{ */
516	/** The handler must run on the EMT. */
517	#define DBGFINFO_FLAGS_RUN_ON_EMT RT_BIT(0)
518	/** @} */
519
520	VMMR3_INT_DECL(int) DBGFR3InfoRegisterDevice(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler, PPDMDEVINS pDevIns);
521	VMMR3_INT_DECL(int) DBGFR3InfoRegisterDriver(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERDRV pfnHandler, PPDMDRVINS pDrvIns);
522	VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternal(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERINT pfnHandler);
523	VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternalEx(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERINT pfnHandler, uint32_t fFlags);
524	VMMR3DECL(int) DBGFR3InfoRegisterExternal(PUVM pUVM, const char pszName, const char pszDesc, PFNDBGFHANDLEREXT pfnHandler, void *pvUser);
525	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName);
526	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName);
527	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterInternal(PVM pVM, const char *pszName);
528	VMMR3DECL(int) DBGFR3InfoDeregisterExternal(PUVM pUVM, const char *pszName);
529	VMMR3DECL(int) DBGFR3Info(PUVM pUVM, const char pszName, const char pszArgs, PCDBGFINFOHLP pHlp);
530	VMMR3DECL(int) DBGFR3InfoEx(PUVM pUVM, VMCPUID idCpu, const char pszName, const char pszArgs, PCDBGFINFOHLP pHlp);
531	VMMR3DECL(int) DBGFR3InfoLogRel(PUVM pUVM, const char pszName, const char pszArgs);
532	VMMR3DECL(int) DBGFR3InfoStdErr(PUVM pUVM, const char pszName, const char pszArgs);
533	VMMR3_INT_DECL(int) DBGFR3InfoMulti(PVM pVM, const char pszIncludePat, const char pszExcludePat,
534	const char *pszSepFmt, PCDBGFINFOHLP pHlp);
535
536	/** @def DBGFR3InfoLog
537	* Display a piece of info writing to the log if enabled.
538	*
539	* @param a_pVM The shared VM handle.
540	* @param a_pszName The identifier of the info to display.
541	* @param a_pszArgs Arguments to the info handler.
542	*/
543	#ifdef LOG_ENABLED
544	# define DBGFR3_INFO_LOG(a_pVM, a_pszName, a_pszArgs) \
545	do { \
546	if (LogIsEnabled()) \
547	DBGFR3Info((a_pVM)->pUVM, a_pszName, a_pszArgs, NULL); \
548	} while (0)
549	#else
550	# define DBGFR3_INFO_LOG(a_pVM, a_pszName, a_pszArgs) do { } while (0)
551	#endif
552
553	/**
554	* Enumeration callback for use with DBGFR3InfoEnum.
555	*
556	* @returns VBox status code.
557	* A status code indicating failure will end the enumeration
558	* and DBGFR3InfoEnum will return with that status code.
559	* @param pUVM The user mode VM handle.
560	* @param pszName Info identifier name.
561	* @param pszDesc The description.
562	*/
563	typedef DECLCALLBACK(int) FNDBGFINFOENUM(PUVM pUVM, const char pszName, const char pszDesc, void *pvUser);
564	/** Pointer to a FNDBGFINFOENUM function. */
565	typedef FNDBGFINFOENUM *PFNDBGFINFOENUM;
566
567	VMMR3DECL(int) DBGFR3InfoEnum(PUVM pUVM, PFNDBGFINFOENUM pfnCallback, void *pvUser);
568	VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogHlp(void);
569	VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogRelHlp(void);
570
571	#endif /* IN_RING3 */
572
573
574	#ifdef IN_RING3 /* The log contrl API only works in ring-3. */
575	VMMR3DECL(int) DBGFR3LogModifyGroups(PUVM pUVM, const char *pszGroupSettings);
576	VMMR3DECL(int) DBGFR3LogModifyFlags(PUVM pUVM, const char *pszFlagSettings);
577	VMMR3DECL(int) DBGFR3LogModifyDestinations(PUVM pUVM, const char *pszDestSettings);
578	#endif /* IN_RING3 */
579
580	#ifdef IN_RING3 /* The debug information management APIs only works in ring-3. */
581
582	/** Max length (including '\\0') of a symbol name. */
583	#define DBGF_SYMBOL_NAME_LENGTH 512
584
585	/**
586	* Debug symbol.
587	*/
588	typedef struct DBGFSYMBOL
589	{
590	/** Symbol value (address). */
591	RTGCUINTPTR Value;
592	/** Symbol size. */
593	uint32_t cb;
594	/** Symbol Flags. (reserved). */
595	uint32_t fFlags;
596	/** Symbol name. */
597	char szName[DBGF_SYMBOL_NAME_LENGTH];
598	} DBGFSYMBOL;
599	/** Pointer to debug symbol. */
600	typedef DBGFSYMBOL *PDBGFSYMBOL;
601	/** Pointer to const debug symbol. */
602	typedef const DBGFSYMBOL *PCDBGFSYMBOL;
603
604	/**
605	* Debug line number information.
606	*/
607	typedef struct DBGFLINE
608	{
609	/** Address. */
610	RTGCUINTPTR Address;
611	/** Line number. */
612	uint32_t uLineNo;
613	/** Filename. */
614	char szFilename[260];
615	} DBGFLINE;
616	/** Pointer to debug line number. */
617	typedef DBGFLINE *PDBGFLINE;
618	/** Pointer to const debug line number. */
619	typedef const DBGFLINE *PCDBGFLINE;
620
621	/** @name Address spaces aliases.
622	* @{ */
623	/** The guest global address space. */
624	#define DBGF_AS_GLOBAL ((RTDBGAS)-1)
625	/** The guest kernel address space.
626	* This is usually resolves to the same as DBGF_AS_GLOBAL. */
627	#define DBGF_AS_KERNEL ((RTDBGAS)-2)
628	/** The physical address space. */
629	#define DBGF_AS_PHYS ((RTDBGAS)-3)
630	/** Raw-mode context. */
631	#define DBGF_AS_RC ((RTDBGAS)-4)
632	/** Ring-0 context. */
633	#define DBGF_AS_R0 ((RTDBGAS)-5)
634	/** Raw-mode context and then global guest context.
635	* When used for looking up information, it works as if the call was first made
636	* with DBGF_AS_RC and then on failure with DBGF_AS_GLOBAL. When called for
637	* making address space changes, it works as if DBGF_AS_RC was used. */
638	#define DBGF_AS_RC_AND_GC_GLOBAL ((RTDBGAS)-6)
639
640	/** The first special one. */
641	#define DBGF_AS_FIRST DBGF_AS_RC_AND_GC_GLOBAL
642	/** The last special one. */
643	#define DBGF_AS_LAST DBGF_AS_GLOBAL
644	#endif
645	/** The number of special address space handles. */
646	#define DBGF_AS_COUNT (6U)
647	#ifdef IN_RING3
648	/** Converts an alias handle to an array index. */
649	#define DBGF_AS_ALIAS_2_INDEX(hAlias) \
650	( (uintptr_t)(hAlias) - (uintptr_t)DBGF_AS_FIRST )
651	/** Predicat macro that check if the specified handle is an alias. */
652	#define DBGF_AS_IS_ALIAS(hAlias) \
653	( DBGF_AS_ALIAS_2_INDEX(hAlias) < DBGF_AS_COUNT )
654	/** Predicat macro that check if the specified alias is a fixed one or not. */
655	#define DBGF_AS_IS_FIXED_ALIAS(hAlias) \
656	( DBGF_AS_ALIAS_2_INDEX(hAlias) < (uintptr_t)DBGF_AS_PHYS - (uintptr_t)DBGF_AS_FIRST + 1U )
657
658	/** @} */
659
660	VMMR3DECL(RTDBGCFG) DBGFR3AsGetConfig(PUVM pUVM);
661
662	VMMR3DECL(int) DBGFR3AsAdd(PUVM pUVM, RTDBGAS hDbgAs, RTPROCESS ProcId);
663	VMMR3DECL(int) DBGFR3AsDelete(PUVM pUVM, RTDBGAS hDbgAs);
664	VMMR3DECL(int) DBGFR3AsSetAlias(PUVM pUVM, RTDBGAS hAlias, RTDBGAS hAliasFor);
665	VMMR3DECL(RTDBGAS) DBGFR3AsResolve(PUVM pUVM, RTDBGAS hAlias);
666	VMMR3DECL(RTDBGAS) DBGFR3AsResolveAndRetain(PUVM pUVM, RTDBGAS hAlias);
667	VMMR3DECL(RTDBGAS) DBGFR3AsQueryByName(PUVM pUVM, const char *pszName);
668	VMMR3DECL(RTDBGAS) DBGFR3AsQueryByPid(PUVM pUVM, RTPROCESS ProcId);
669
670	VMMR3DECL(int) DBGFR3AsLoadImage(PUVM pUVM, RTDBGAS hDbgAs, const char pszFilename, const char pszModName, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, uint32_t fFlags);
671	VMMR3DECL(int) DBGFR3AsLoadMap(PUVM pUVM, RTDBGAS hDbgAs, const char pszFilename, const char pszModName, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, RTGCUINTPTR uSubtrahend, uint32_t fFlags);
672	VMMR3DECL(int) DBGFR3AsLinkModule(PUVM pUVM, RTDBGAS hDbgAs, RTDBGMOD hMod, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, uint32_t fFlags);
673
674	VMMR3DECL(int) DBGFR3AsSymbolByAddr(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress, uint32_t fFlags,
675	PRTGCINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
676	VMMR3DECL(PRTDBGSYMBOL) DBGFR3AsSymbolByAddrA(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress, uint32_t Flags,
677	PRTGCINTPTR poffDisp, PRTDBGMOD phMod);
678	VMMR3DECL(int) DBGFR3AsSymbolByName(PUVM pUVM, RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
679
680	VMMR3DECL(int) DBGFR3AsLineByAddr(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress,
681	PRTGCINTPTR poffDisp, PRTDBGLINE pLine, PRTDBGMOD phMod);
682	VMMR3DECL(PRTDBGLINE) DBGFR3AsLineByAddrA(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress,
683	PRTGCINTPTR poffDisp, PRTDBGMOD phMod);
684
685	#endif /* IN_RING3 */
686
687	#ifdef IN_RING3 /* The stack API only works in ring-3. */
688
689	/**
690	* Return type.
691	*/
692	typedef enum DBGFRETRUNTYPE
693	{
694	/** The usual invalid 0 value. */
695	DBGFRETURNTYPE_INVALID = 0,
696	/** Near 16-bit return. */
697	DBGFRETURNTYPE_NEAR16,
698	/** Near 32-bit return. */
699	DBGFRETURNTYPE_NEAR32,
700	/** Near 64-bit return. */
701	DBGFRETURNTYPE_NEAR64,
702	/** Far 16:16 return. */
703	DBGFRETURNTYPE_FAR16,
704	/** Far 16:32 return. */
705	DBGFRETURNTYPE_FAR32,
706	/** Far 16:64 return. */
707	DBGFRETURNTYPE_FAR64,
708	/** 16-bit iret return (e.g. real or 286 protect mode). */
709	DBGFRETURNTYPE_IRET16,
710	/** 32-bit iret return. */
711	DBGFRETURNTYPE_IRET32,
712	/** 32-bit iret return. */
713	DBGFRETURNTYPE_IRET32_PRIV,
714	/** 32-bit iret return to V86 mode. */
715	DBGFRETURNTYPE_IRET32_V86,
716	/** @todo 64-bit iret return. */
717	DBGFRETURNTYPE_IRET64,
718	/** The end of the valid return types. */
719	DBGFRETURNTYPE_END,
720	/** The usual 32-bit blowup. */
721	DBGFRETURNTYPE_32BIT_HACK = 0x7fffffff
722	} DBGFRETURNTYPE;
723
724	/**
725	* Figures the size of the return state on the stack.
726	*
727	* @returns number of bytes. 0 if invalid parameter.
728	* @param enmRetType The type of return.
729	*/
730	DECLINLINE(unsigned) DBGFReturnTypeSize(DBGFRETURNTYPE enmRetType)
731	{
732	switch (enmRetType)
733	{
734	case DBGFRETURNTYPE_NEAR16: return 2;
735	case DBGFRETURNTYPE_NEAR32: return 4;
736	case DBGFRETURNTYPE_NEAR64: return 8;
737	case DBGFRETURNTYPE_FAR16: return 4;
738	case DBGFRETURNTYPE_FAR32: return 4;
739	case DBGFRETURNTYPE_FAR64: return 8;
740	case DBGFRETURNTYPE_IRET16: return 6;
741	case DBGFRETURNTYPE_IRET32: return 4*3;
742	case DBGFRETURNTYPE_IRET32_PRIV: return 4*5;
743	case DBGFRETURNTYPE_IRET32_V86: return 4*9;
744	case DBGFRETURNTYPE_IRET64:
745	default:
746	return 0;
747	}
748	}
749
750
751	/** Pointer to stack frame info. */
752	typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
753	/** Pointer to const stack frame info. */
754	typedef struct DBGFSTACKFRAME const *PCDBGFSTACKFRAME;
755	/**
756	* Info about a stack frame.
757	*/
758	typedef struct DBGFSTACKFRAME
759	{
760	/** Frame number. */
761	uint32_t iFrame;
762	/** Frame flags. */
763	uint32_t fFlags;
764	/** The frame address.
765	* The off member is [e\|r]bp and the Sel member is ss. */
766	DBGFADDRESS AddrFrame;
767	/** The stack address of the frame.
768	* The off member is [e\|r]sp and the Sel member is ss. */
769	DBGFADDRESS AddrStack;
770	/** The program counter (PC) address of the frame.
771	* The off member is [e\|r]ip and the Sel member is cs. */
772	DBGFADDRESS AddrPC;
773	/** Pointer to the symbol nearest the program counter (PC). NULL if not found. */
774	PRTDBGSYMBOL pSymPC;
775	/** Pointer to the linnumber nearest the program counter (PC). NULL if not found. */
776	PRTDBGLINE pLinePC;
777
778	/** The return frame address.
779	* The off member is [e\|r]bp and the Sel member is ss. */
780	DBGFADDRESS AddrReturnFrame;
781	/** The return stack address.
782	* The off member is [e\|r]sp and the Sel member is ss. */
783	DBGFADDRESS AddrReturnStack;
784	/** The way this frame returns to the next one. */
785	DBGFRETURNTYPE enmReturnType;
786
787	/** The program counter (PC) address which the frame returns to.
788	* The off member is [e\|r]ip and the Sel member is cs. */
789	DBGFADDRESS AddrReturnPC;
790	/** Pointer to the symbol nearest the return PC. NULL if not found. */
791	PRTDBGSYMBOL pSymReturnPC;
792	/** Pointer to the linnumber nearest the return PC. NULL if not found. */
793	PRTDBGLINE pLineReturnPC;
794
795	/** 32-bytes of stack arguments. */
796	union
797	{
798	/** 64-bit view */
799	uint64_t au64[4];
800	/** 32-bit view */
801	uint32_t au32[8];
802	/** 16-bit view */
803	uint16_t au16[16];
804	/** 8-bit view */
805	uint8_t au8[32];
806	} Args;
807
808	/** Pointer to the next frame.
809	* Might not be used in some cases, so consider it internal. */
810	PCDBGFSTACKFRAME pNextInternal;
811	/** Pointer to the first frame.
812	* Might not be used in some cases, so consider it internal. */
813	PCDBGFSTACKFRAME pFirstInternal;
814	} DBGFSTACKFRAME;
815
816	/** @name DBGFSTACKFRAME Flags.
817	* @{ */
818	/** Set if the content of the frame is filled in by DBGFR3StackWalk() and can be used
819	* to construct the next frame. */
820	# define DBGFSTACKFRAME_FLAGS_ALL_VALID RT_BIT(0)
821	/** This is the last stack frame we can read.
822	* This flag is not set if the walk stop because of max dept or recursion. */
823	# define DBGFSTACKFRAME_FLAGS_LAST RT_BIT(1)
824	/** This is the last record because we detected a loop. */
825	# define DBGFSTACKFRAME_FLAGS_LOOP RT_BIT(2)
826	/** This is the last record because we reached the maximum depth. */
827	# define DBGFSTACKFRAME_FLAGS_MAX_DEPTH RT_BIT(3)
828	/** 16-bit frame. */
829	# define DBGFSTACKFRAME_FLAGS_16BIT RT_BIT(4)
830	/** 32-bit frame. */
831	# define DBGFSTACKFRAME_FLAGS_32BIT RT_BIT(5)
832	/** 64-bit frame. */
833	# define DBGFSTACKFRAME_FLAGS_64BIT RT_BIT(6)
834	/** @} */
835
836	/** @name DBGFCODETYPE
837	* @{ */
838	typedef enum DBGFCODETYPE
839	{
840	/** The usual invalid 0 value. */
841	DBGFCODETYPE_INVALID = 0,
842	/** Stack walk for guest code. */
843	DBGFCODETYPE_GUEST,
844	/** Stack walk for hypervisor code. */
845	DBGFCODETYPE_HYPER,
846	/** Stack walk for ring 0 code. */
847	DBGFCODETYPE_RING0,
848	/** The usual 32-bit blowup. */
849	DBGFCODETYPE_32BIT_HACK = 0x7fffffff
850	} DBGFCODETYPE;
851	/** @} */
852
853	VMMR3DECL(int) DBGFR3StackWalkBegin(PUVM pUVM, VMCPUID idCpu, DBGFCODETYPE enmCodeType,
854	PCDBGFSTACKFRAME *ppFirstFrame);
855	VMMR3DECL(int) DBGFR3StackWalkBeginEx(PUVM pUVM, VMCPUID idCpu, DBGFCODETYPE enmCodeType, PCDBGFADDRESS pAddrFrame,
856	PCDBGFADDRESS pAddrStack,PCDBGFADDRESS pAddrPC,
857	DBGFRETURNTYPE enmReturnType, PCDBGFSTACKFRAME *ppFirstFrame);
858	VMMR3DECL(PCDBGFSTACKFRAME) DBGFR3StackWalkNext(PCDBGFSTACKFRAME pCurrent);
859	VMMR3DECL(void) DBGFR3StackWalkEnd(PCDBGFSTACKFRAME pFirstFrame);
860
861	#endif /* IN_RING3 */
862
863
864	#ifdef IN_RING3 /* The disassembly API only works in ring-3. */
865
866	/** Flags to pass to DBGFR3DisasInstrEx().
867	* @{ */
868	/** Disassemble the current guest instruction, with annotations. */
869	#define DBGF_DISAS_FLAGS_CURRENT_GUEST RT_BIT(0)
870	/** Disassemble the current hypervisor instruction, with annotations. */
871	#define DBGF_DISAS_FLAGS_CURRENT_HYPER RT_BIT(1)
872	/** No annotations for current context. */
873	#define DBGF_DISAS_FLAGS_NO_ANNOTATION RT_BIT(2)
874	/** No symbol lookup. */
875	#define DBGF_DISAS_FLAGS_NO_SYMBOLS RT_BIT(3)
876	/** No instruction bytes. */
877	#define DBGF_DISAS_FLAGS_NO_BYTES RT_BIT(4)
878	/** No address in the output. */
879	#define DBGF_DISAS_FLAGS_NO_ADDRESS RT_BIT(5)
880	/** Probably a hypervisor instruction. */
881	#define DBGF_DISAS_FLAGS_HYPER RT_BIT(6)
882	/** Disassemble original unpatched bytes (PATM). */
883	#define DBGF_DISAS_FLAGS_UNPATCHED_BYTES RT_BIT(7)
884	/** Annotate patched instructions. */
885	#define DBGF_DISAS_FLAGS_ANNOTATE_PATCHED RT_BIT(8)
886	/** Disassemble in the default mode of the specific context. */
887	#define DBGF_DISAS_FLAGS_DEFAULT_MODE UINT32_C(0x00000000)
888	/** Disassemble in 16-bit mode. */
889	#define DBGF_DISAS_FLAGS_16BIT_MODE UINT32_C(0x10000000)
890	/** Disassemble in 16-bit mode with real mode address translation. */
891	#define DBGF_DISAS_FLAGS_16BIT_REAL_MODE UINT32_C(0x20000000)
892	/** Disassemble in 32-bit mode. */
893	#define DBGF_DISAS_FLAGS_32BIT_MODE UINT32_C(0x30000000)
894	/** Disassemble in 64-bit mode. */
895	#define DBGF_DISAS_FLAGS_64BIT_MODE UINT32_C(0x40000000)
896	/** The disassembly mode mask. */
897	#define DBGF_DISAS_FLAGS_MODE_MASK UINT32_C(0x70000000)
898	/** Mask containing the valid flags. */
899	#define DBGF_DISAS_FLAGS_VALID_MASK UINT32_C(0x700001ff)
900	/** @} */
901
902	/** Special flat selector. */
903	#define DBGF_SEL_FLAT 1
904
905	VMMR3DECL(int) DBGFR3DisasInstrEx(PUVM pUVM, VMCPUID idCpu, RTSEL Sel, RTGCPTR GCPtr, uint32_t fFlags,
906	char pszOutput, uint32_t cbOutput, uint32_t pcbInstr);
907	VMMR3_INT_DECL(int) DBGFR3DisasInstrCurrent(PVMCPU pVCpu, char *pszOutput, uint32_t cbOutput);
908	VMMR3DECL(int) DBGFR3DisasInstrCurrentLogInternal(PVMCPU pVCpu, const char *pszPrefix);
909
910	/** @def DBGFR3DisasInstrCurrentLog
911	* Disassembles the current guest context instruction and writes it to the log.
912	* All registers and data will be displayed. Addresses will be attempted resolved to symbols.
913	*/
914	#ifdef LOG_ENABLED
915	# define DBGFR3_DISAS_INSTR_CUR_LOG(pVCpu, pszPrefix) \
916	do { \
917	if (LogIsEnabled()) \
918	DBGFR3DisasInstrCurrentLogInternal(pVCpu, pszPrefix); \
919	} while (0)
920	#else
921	# define DBGFR3_DISAS_INSTR_CUR_LOG(pVCpu, pszPrefix) do { } while (0)
922	#endif
923
924	VMMR3DECL(int) DBGFR3DisasInstrLogInternal(PVMCPU pVCpu, RTSEL Sel, RTGCPTR GCPtr, const char *pszPrefix);
925
926	/** @def DBGFR3DisasInstrLog
927	* Disassembles the specified guest context instruction and writes it to the log.
928	* Addresses will be attempted resolved to symbols.
929	* @thread Any EMT.
930	*/
931	# ifdef LOG_ENABLED
932	# define DBGFR3_DISAS_INSTR_LOG(pVCpu, Sel, GCPtr, pszPrefix) \
933	do { \
934	if (LogIsEnabled()) \
935	DBGFR3DisasInstrLogInternal(pVCpu, Sel, GCPtr, pszPrefix); \
936	} while (0)
937	# else
938	# define DBGFR3_DISAS_INSTR_LOG(pVCpu, Sel, GCPtr, pszPrefix) do { } while (0)
939	# endif
940	#endif
941
942
943	#ifdef IN_RING3
944	VMMR3DECL(int) DBGFR3MemScan(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, RTGCUINTPTR cbRange, RTGCUINTPTR uAlign,
945	const void *pvNeedle, size_t cbNeedle, PDBGFADDRESS pHitAddress);
946	VMMR3DECL(int) DBGFR3MemRead(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void *pvBuf, size_t cbRead);
947	VMMR3DECL(int) DBGFR3MemReadString(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, char *pszBuf, size_t cbBuf);
948	VMMR3DECL(int) DBGFR3MemWrite(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void const *pvBuf, size_t cbRead);
949	#endif
950
951
952	/** @name Flags for DBGFR3PagingDumpEx, PGMR3DumpHierarchyHCEx and
953	* PGMR3DumpHierarchyGCEx
954	* @{ */
955	/** The CR3 from the current CPU state. */
956	#define DBGFPGDMP_FLAGS_CURRENT_CR3 RT_BIT_32(0)
957	/** The current CPU paging mode (PSE, PAE, LM, EPT, NX). */
958	#define DBGFPGDMP_FLAGS_CURRENT_MODE RT_BIT_32(1)
959	/** Whether PSE is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
960	* Same value as X86_CR4_PSE. */
961	#define DBGFPGDMP_FLAGS_PSE RT_BIT_32(4) /* */
962	/** Whether PAE is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
963	* Same value as X86_CR4_PAE. */
964	#define DBGFPGDMP_FLAGS_PAE RT_BIT_32(5) /* */
965	/** Whether LME is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
966	* Same value as MSR_K6_EFER_LME. */
967	#define DBGFPGDMP_FLAGS_LME RT_BIT_32(8)
968	/** Whether nested paging is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE). */
969	#define DBGFPGDMP_FLAGS_NP RT_BIT_32(9)
970	/** Whether extended nested page tables are enabled
971	* (!DBGFPGDMP_FLAGS_CURRENT_STATE). */
972	#define DBGFPGDMP_FLAGS_EPT RT_BIT_32(10)
973	/** Whether no-execution is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
974	* Same value as MSR_K6_EFER_NXE. */
975	#define DBGFPGDMP_FLAGS_NXE RT_BIT_32(11)
976	/** Whether to print the CR3. */
977	#define DBGFPGDMP_FLAGS_PRINT_CR3 RT_BIT_32(27)
978	/** Whether to print the header. */
979	#define DBGFPGDMP_FLAGS_HEADER RT_BIT_32(28)
980	/** Whether to dump additional page information. */
981	#define DBGFPGDMP_FLAGS_PAGE_INFO RT_BIT_32(29)
982	/** Dump the shadow tables if set.
983	* Cannot be used together with DBGFPGDMP_FLAGS_GUEST. */
984	#define DBGFPGDMP_FLAGS_SHADOW RT_BIT_32(30)
985	/** Dump the guest tables if set.
986	* Cannot be used together with DBGFPGDMP_FLAGS_SHADOW. */
987	#define DBGFPGDMP_FLAGS_GUEST RT_BIT_32(31)
988	/** Mask of valid bits. */
989	#define DBGFPGDMP_FLAGS_VALID_MASK UINT32_C(0xf8000f33)
990	/** The mask of bits controlling the paging mode. */
991	#define DBGFPGDMP_FLAGS_MODE_MASK UINT32_C(0x00000f32)
992	/** @} */
993	VMMDECL(int) DBGFR3PagingDumpEx(PUVM pUVM, VMCPUID idCpu, uint32_t fFlags, uint64_t cr3, uint64_t u64FirstAddr,
994	uint64_t u64LastAddr, uint32_t cMaxDepth, PCDBGFINFOHLP pHlp);
995
996
997	/** @name DBGFR3SelQueryInfo flags.
998	* @{ */
999	/** Get the info from the guest descriptor table. */
1000	#define DBGFSELQI_FLAGS_DT_GUEST UINT32_C(0)
1001	/** Get the info from the shadow descriptor table.
1002	* Only works in raw-mode. */
1003	#define DBGFSELQI_FLAGS_DT_SHADOW UINT32_C(1)
1004	/** If currently executing in in 64-bit mode, blow up data selectors. */
1005	#define DBGFSELQI_FLAGS_DT_ADJ_64BIT_MODE UINT32_C(2)
1006	/** @} */
1007	VMMR3DECL(int) DBGFR3SelQueryInfo(PUVM pUVM, VMCPUID idCpu, RTSEL Sel, uint32_t fFlags, PDBGFSELINFO pSelInfo);
1008
1009
1010	/**
1011	* Register identifiers.
1012	*/
1013	typedef enum DBGFREG
1014	{
1015	/* General purpose registers: */
1016	DBGFREG_AL = 0,
1017	DBGFREG_AX = DBGFREG_AL,
1018	DBGFREG_EAX = DBGFREG_AL,
1019	DBGFREG_RAX = DBGFREG_AL,
1020
1021	DBGFREG_CL,
1022	DBGFREG_CX = DBGFREG_CL,
1023	DBGFREG_ECX = DBGFREG_CL,
1024	DBGFREG_RCX = DBGFREG_CL,
1025
1026	DBGFREG_DL,
1027	DBGFREG_DX = DBGFREG_DL,
1028	DBGFREG_EDX = DBGFREG_DL,
1029	DBGFREG_RDX = DBGFREG_DL,
1030
1031	DBGFREG_BL,
1032	DBGFREG_BX = DBGFREG_BL,
1033	DBGFREG_EBX = DBGFREG_BL,
1034	DBGFREG_RBX = DBGFREG_BL,
1035
1036	DBGFREG_SPL,
1037	DBGFREG_SP = DBGFREG_SPL,
1038	DBGFREG_ESP = DBGFREG_SPL,
1039	DBGFREG_RSP = DBGFREG_SPL,
1040
1041	DBGFREG_BPL,
1042	DBGFREG_BP = DBGFREG_BPL,
1043	DBGFREG_EBP = DBGFREG_BPL,
1044	DBGFREG_RBP = DBGFREG_BPL,
1045
1046	DBGFREG_SIL,
1047	DBGFREG_SI = DBGFREG_SIL,
1048	DBGFREG_ESI = DBGFREG_SIL,
1049	DBGFREG_RSI = DBGFREG_SIL,
1050
1051	DBGFREG_DIL,
1052	DBGFREG_DI = DBGFREG_DIL,
1053	DBGFREG_EDI = DBGFREG_DIL,
1054	DBGFREG_RDI = DBGFREG_DIL,
1055
1056	DBGFREG_R8,
1057	DBGFREG_R8B = DBGFREG_R8,
1058	DBGFREG_R8W = DBGFREG_R8,
1059	DBGFREG_R8D = DBGFREG_R8,
1060
1061	DBGFREG_R9,
1062	DBGFREG_R9B = DBGFREG_R9,
1063	DBGFREG_R9W = DBGFREG_R9,
1064	DBGFREG_R9D = DBGFREG_R9,
1065
1066	DBGFREG_R10,
1067	DBGFREG_R10B = DBGFREG_R10,
1068	DBGFREG_R10W = DBGFREG_R10,
1069	DBGFREG_R10D = DBGFREG_R10,
1070
1071	DBGFREG_R11,
1072	DBGFREG_R11B = DBGFREG_R11,
1073	DBGFREG_R11W = DBGFREG_R11,
1074	DBGFREG_R11D = DBGFREG_R11,
1075
1076	DBGFREG_R12,
1077	DBGFREG_R12B = DBGFREG_R12,
1078	DBGFREG_R12W = DBGFREG_R12,
1079	DBGFREG_R12D = DBGFREG_R12,
1080
1081	DBGFREG_R13,
1082	DBGFREG_R13B = DBGFREG_R13,
1083	DBGFREG_R13W = DBGFREG_R13,
1084	DBGFREG_R13D = DBGFREG_R13,
1085
1086	DBGFREG_R14,
1087	DBGFREG_R14B = DBGFREG_R14,
1088	DBGFREG_R14W = DBGFREG_R14,
1089	DBGFREG_R14D = DBGFREG_R14,
1090
1091	DBGFREG_R15,
1092	DBGFREG_R15B = DBGFREG_R15,
1093	DBGFREG_R15W = DBGFREG_R15,
1094	DBGFREG_R15D = DBGFREG_R15,
1095
1096	/* Segments and other special registers: */
1097	DBGFREG_CS,
1098	DBGFREG_CS_ATTR,
1099	DBGFREG_CS_BASE,
1100	DBGFREG_CS_LIMIT,
1101
1102	DBGFREG_DS,
1103	DBGFREG_DS_ATTR,
1104	DBGFREG_DS_BASE,
1105	DBGFREG_DS_LIMIT,
1106
1107	DBGFREG_ES,
1108	DBGFREG_ES_ATTR,
1109	DBGFREG_ES_BASE,
1110	DBGFREG_ES_LIMIT,
1111
1112	DBGFREG_FS,
1113	DBGFREG_FS_ATTR,
1114	DBGFREG_FS_BASE,
1115	DBGFREG_FS_LIMIT,
1116
1117	DBGFREG_GS,
1118	DBGFREG_GS_ATTR,
1119	DBGFREG_GS_BASE,
1120	DBGFREG_GS_LIMIT,
1121
1122	DBGFREG_SS,
1123	DBGFREG_SS_ATTR,
1124	DBGFREG_SS_BASE,
1125	DBGFREG_SS_LIMIT,
1126
1127	DBGFREG_IP,
1128	DBGFREG_EIP = DBGFREG_IP,
1129	DBGFREG_RIP = DBGFREG_IP,
1130
1131	DBGFREG_FLAGS,
1132	DBGFREG_EFLAGS = DBGFREG_FLAGS,
1133	DBGFREG_RFLAGS = DBGFREG_FLAGS,
1134
1135	/* FPU: */
1136	DBGFREG_FCW,
1137	DBGFREG_FSW,
1138	DBGFREG_FTW,
1139	DBGFREG_FOP,
1140	DBGFREG_FPUIP,
1141	DBGFREG_FPUCS,
1142	DBGFREG_FPUDP,
1143	DBGFREG_FPUDS,
1144	DBGFREG_MXCSR,
1145	DBGFREG_MXCSR_MASK,
1146
1147	DBGFREG_ST0,
1148	DBGFREG_ST1,
1149	DBGFREG_ST2,
1150	DBGFREG_ST3,
1151	DBGFREG_ST4,
1152	DBGFREG_ST5,
1153	DBGFREG_ST6,
1154	DBGFREG_ST7,
1155
1156	DBGFREG_MM0,
1157	DBGFREG_MM1,
1158	DBGFREG_MM2,
1159	DBGFREG_MM3,
1160	DBGFREG_MM4,
1161	DBGFREG_MM5,
1162	DBGFREG_MM6,
1163	DBGFREG_MM7,
1164
1165	/* SSE: */
1166	DBGFREG_XMM0,
1167	DBGFREG_XMM1,
1168	DBGFREG_XMM2,
1169	DBGFREG_XMM3,
1170	DBGFREG_XMM4,
1171	DBGFREG_XMM5,
1172	DBGFREG_XMM6,
1173	DBGFREG_XMM7,
1174	DBGFREG_XMM8,
1175	DBGFREG_XMM9,
1176	DBGFREG_XMM10,
1177	DBGFREG_XMM11,
1178	DBGFREG_XMM12,
1179	DBGFREG_XMM13,
1180	DBGFREG_XMM14,
1181	DBGFREG_XMM15,
1182	/** @todo add XMM aliases. */
1183
1184	/* System registers: */
1185	DBGFREG_GDTR_BASE,
1186	DBGFREG_GDTR_LIMIT,
1187	DBGFREG_IDTR_BASE,
1188	DBGFREG_IDTR_LIMIT,
1189	DBGFREG_LDTR,
1190	DBGFREG_LDTR_ATTR,
1191	DBGFREG_LDTR_BASE,
1192	DBGFREG_LDTR_LIMIT,
1193	DBGFREG_TR,
1194	DBGFREG_TR_ATTR,
1195	DBGFREG_TR_BASE,
1196	DBGFREG_TR_LIMIT,
1197
1198	DBGFREG_CR0,
1199	DBGFREG_CR2,
1200	DBGFREG_CR3,
1201	DBGFREG_CR4,
1202	DBGFREG_CR8,
1203
1204	DBGFREG_DR0,
1205	DBGFREG_DR1,
1206	DBGFREG_DR2,
1207	DBGFREG_DR3,
1208	DBGFREG_DR6,
1209	DBGFREG_DR7,
1210
1211	/* MSRs: */
1212	DBGFREG_MSR_IA32_APICBASE,
1213	DBGFREG_MSR_IA32_CR_PAT,
1214	DBGFREG_MSR_IA32_PERF_STATUS,
1215	DBGFREG_MSR_IA32_SYSENTER_CS,
1216	DBGFREG_MSR_IA32_SYSENTER_EIP,
1217	DBGFREG_MSR_IA32_SYSENTER_ESP,
1218	DBGFREG_MSR_IA32_TSC,
1219	DBGFREG_MSR_K6_EFER,
1220	DBGFREG_MSR_K6_STAR,
1221	DBGFREG_MSR_K8_CSTAR,
1222	DBGFREG_MSR_K8_FS_BASE,
1223	DBGFREG_MSR_K8_GS_BASE,
1224	DBGFREG_MSR_K8_KERNEL_GS_BASE,
1225	DBGFREG_MSR_K8_LSTAR,
1226	DBGFREG_MSR_K8_SF_MASK,
1227	DBGFREG_MSR_K8_TSC_AUX,
1228
1229	/** The number of registers to pass to DBGFR3RegQueryAll. */
1230	DBGFREG_ALL_COUNT,
1231
1232	/* Misc aliases that doesn't need be part of the 'all' query: */
1233	DBGFREG_AH = DBGFREG_ALL_COUNT,
1234	DBGFREG_CH,
1235	DBGFREG_DH,
1236	DBGFREG_BH,
1237	DBGFREG_GDTR,
1238	DBGFREG_IDTR,
1239
1240	/** The end of the registers. */
1241	DBGFREG_END,
1242	/** The usual 32-bit type hack. */
1243	DBGFREG_32BIT_HACK = 0x7fffffff
1244	} DBGFREG;
1245	/** Pointer to a register identifier. */
1246	typedef DBGFREG *PDBGFREG;
1247	/** Pointer to a const register identifier. */
1248	typedef DBGFREG const *PCDBGFREG;
1249
1250	/**
1251	* Register value type.
1252	*/
1253	typedef enum DBGFREGVALTYPE
1254	{
1255	DBGFREGVALTYPE_INVALID = 0,
1256	/** Unsigned 8-bit register value. */
1257	DBGFREGVALTYPE_U8,
1258	/** Unsigned 16-bit register value. */
1259	DBGFREGVALTYPE_U16,
1260	/** Unsigned 32-bit register value. */
1261	DBGFREGVALTYPE_U32,
1262	/** Unsigned 64-bit register value. */
1263	DBGFREGVALTYPE_U64,
1264	/** Unsigned 128-bit register value. */
1265	DBGFREGVALTYPE_U128,
1266	/** Long double register value. */
1267	DBGFREGVALTYPE_R80,
1268	/** Descriptor table register value. */
1269	DBGFREGVALTYPE_DTR,
1270	/** End of the valid register value types. */
1271	DBGFREGVALTYPE_END,
1272	/** The usual 32-bit type hack. */
1273	DBGFREGVALTYPE_32BIT_HACK = 0x7fffffff
1274	} DBGFREGVALTYPE;
1275	/** Pointer to a register value type. */
1276	typedef DBGFREGVALTYPE *PDBGFREGVALTYPE;
1277
1278	/**
1279	* A generic register value type.
1280	*/
1281	typedef union DBGFREGVAL
1282	{
1283	uint8_t u8; /*< The 8-bit view. /
1284	uint16_t u16; /*< The 16-bit view. /
1285	uint32_t u32; /*< The 32-bit view. /
1286	uint64_t u64; /*< The 64-bit view. /
1287	RTUINT128U u128; /*< The 128-bit view. /
1288	RTFLOAT80U r80; /*< The 80-bit floating point view. /
1289	RTFLOAT80U2 r80Ex; /*< The 80-bit floating point view v2. /
1290	/** GDTR or LDTR (DBGFREGVALTYPE_DTR). */
1291	struct
1292	{
1293	/** The table address. */
1294	uint64_t u64Base;
1295	/** The table limit (length minus 1). */
1296	uint32_t u32Limit;
1297	} dtr;
1298
1299	uint8_t au8[16]; /*< The 8-bit array view. /
1300	uint16_t au16[8]; /*< The 16-bit array view. /
1301	uint32_t au32[4]; /*< The 32-bit array view. /
1302	uint64_t au64[2]; /*< The 64-bit array view. /
1303	RTUINT128U u;
1304	} DBGFREGVAL;
1305	/** Pointer to a generic register value type. */
1306	typedef DBGFREGVAL *PDBGFREGVAL;
1307	/** Pointer to a const generic register value type. */
1308	typedef DBGFREGVAL const *PCDBGFREGVAL;
1309
1310	VMMDECL(ssize_t) DBGFR3RegFormatValue(char *pszBuf, size_t cbBuf, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType, bool fSpecial);
1311	VMMDECL(ssize_t) DBGFR3RegFormatValueEx(char *pszBuf, size_t cbBuf, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType,
1312	unsigned uBase, signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
1313
1314	/**
1315	* Register sub-field descriptor.
1316	*/
1317	typedef struct DBGFREGSUBFIELD
1318	{
1319	/** The name of the sub-field. NULL is used to terminate the array. */
1320	const char *pszName;
1321	/** The index of the first bit. Ignored if pfnGet is set. */
1322	uint8_t iFirstBit;
1323	/** The number of bits. Mandatory. */
1324	uint8_t cBits;
1325	/** The shift count. Not applied when pfnGet is set, but used to
1326	* calculate the minimum type. */
1327	int8_t cShift;
1328	/** Sub-field flags, DBGFREGSUBFIELD_FLAGS_XXX. */
1329	uint8_t fFlags;
1330	/** Getter (optional).
1331	* @remarks Does not take the device lock or anything like that.
1332	*/
1333	DECLCALLBACKMEMBER(int, pfnGet)(void pvUser, struct DBGFREGSUBFIELD const pSubField, PRTUINT128U puValue);
1334	/** Setter (optional).
1335	* @remarks Does not take the device lock or anything like that.
1336	*/
1337	DECLCALLBACKMEMBER(int, pfnSet)(void pvUser, struct DBGFREGSUBFIELD const pSubField, RTUINT128U uValue, RTUINT128U fMask);
1338	} DBGFREGSUBFIELD;
1339	/** Pointer to a const register sub-field descriptor. */
1340	typedef DBGFREGSUBFIELD const *PCDBGFREGSUBFIELD;
1341
1342	/** @name DBGFREGSUBFIELD_FLAGS_XXX
1343	* @{ */
1344	/** The sub-field is read-only. */
1345	#define DBGFREGSUBFIELD_FLAGS_READ_ONLY UINT8_C(0x01)
1346	/** @} */
1347
1348	/** Macro for creating a read-write sub-field entry without getters. */
1349	#define DBGFREGSUBFIELD_RW(a_szName, a_iFirstBit, a_cBits, a_cShift) \
1350	{ a_szName, a_iFirstBit, a_cBits, a_cShift, 0 /fFlags/, NULL /pfnGet/, NULL /pfnSet/ }
1351	/** Macro for creating a read-write sub-field entry with getters. */
1352	#define DBGFREGSUBFIELD_RW_SG(a_szName, a_cBits, a_cShift, a_pfnGet, a_pfnSet) \
1353	{ a_szName, 0 /iFirstBit/, a_cBits, a_cShift, 0 /fFlags/, a_pfnGet, a_pfnSet }
1354	/** Macro for creating a read-only sub-field entry without getters. */
1355	#define DBGFREGSUBFIELD_RO(a_szName, a_iFirstBit, a_cBits, a_cShift) \
1356	{ a_szName, a_iFirstBit, a_cBits, a_cShift, DBGFREGSUBFIELD_FLAGS_READ_ONLY, NULL /pfnGet/, NULL /pfnSet/ }
1357	/** Macro for creating a terminator sub-field entry. */
1358	#define DBGFREGSUBFIELD_TERMINATOR() \
1359	{ NULL, 0, 0, 0, 0, NULL, NULL }
1360
1361	/**
1362	* Register alias descriptor.
1363	*/
1364	typedef struct DBGFREGALIAS
1365	{
1366	/** The alias name. NULL is used to terminate the array. */
1367	const char *pszName;
1368	/** Set to a valid type if the alias has a different type. */
1369	DBGFREGVALTYPE enmType;
1370	} DBGFREGALIAS;
1371	/** Pointer to a const register alias descriptor. */
1372	typedef DBGFREGALIAS const *PCDBGFREGALIAS;
1373
1374	/**
1375	* Register descriptor.
1376	*/
1377	typedef struct DBGFREGDESC
1378	{
1379	/** The normal register name. */
1380	const char *pszName;
1381	/** The register identifier if this is a CPU register. */
1382	DBGFREG enmReg;
1383	/** The default register type. */
1384	DBGFREGVALTYPE enmType;
1385	/** Flags, see DBGFREG_FLAGS_XXX. */
1386	uint32_t fFlags;
1387	/** The internal register indicator.
1388	* For CPU registers this is the offset into the CPUMCTX structure,
1389	* thuse the 'off' prefix. */
1390	uint32_t offRegister;
1391	/** Getter.
1392	* @remarks Does not take the device lock or anything like that.
1393	*/
1394	DECLCALLBACKMEMBER(int, pfnGet)(void pvUser, struct DBGFREGDESC const pDesc, PDBGFREGVAL pValue);
1395	/** Setter.
1396	* @remarks Does not take the device lock or anything like that.
1397	*/
1398	DECLCALLBACKMEMBER(int, pfnSet)(void pvUser, struct DBGFREGDESC const pDesc, PCDBGFREGVAL pValue, PCDBGFREGVAL pfMask);
1399	/** Aliases (optional). */
1400	PCDBGFREGALIAS paAliases;
1401	/** Sub fields (optional). */
1402	PCDBGFREGSUBFIELD paSubFields;
1403	} DBGFREGDESC;
1404
1405	/** @name Macros for constructing DBGFREGDESC arrays.
1406	* @{ */
1407	#define DBGFREGDESC_RW(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet) \
1408	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, NULL /paAlises/, NULL /paSubFields/ }
1409	#define DBGFREGDESC_RO(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet) \
1410	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, NULL /paAlises/, NULL /paSubFields/ }
1411	#define DBGFREGDESC_RW_A(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases) \
1412	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, NULL /paSubFields/ }
1413	#define DBGFREGDESC_RO_A(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases) \
1414	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, NULL /paSubFields/ }
1415	#define DBGFREGDESC_RW_S(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paSubFields) \
1416	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, /paAliases/, a_paSubFields }
1417	#define DBGFREGDESC_RO_S(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paSubFields) \
1418	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, /paAliases/, a_paSubFields }
1419	#define DBGFREGDESC_RW_AS(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields) \
1420	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields }
1421	#define DBGFREGDESC_RO_AS(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields) \
1422	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields }
1423	#define DBGFREGDESC_TERMINATOR() \
1424	{ NULL, DBGFREG_END, DBGFREGVALTYPE_INVALID, 0, 0, NULL, NULL, NULL, NULL }
1425	/** @} */
1426
1427
1428	/** @name DBGFREG_FLAGS_XXX
1429	* @{ */
1430	/** The register is read-only. */
1431	#define DBGFREG_FLAGS_READ_ONLY RT_BIT_32(0)
1432	/** @} */
1433
1434	/**
1435	* Entry in a batch query or set operation.
1436	*/
1437	typedef struct DBGFREGENTRY
1438	{
1439	/** The register identifier. */
1440	DBGFREG enmReg;
1441	/** The size of the value in bytes. */
1442	DBGFREGVALTYPE enmType;
1443	/** The register value. The valid view is indicated by enmType. */
1444	DBGFREGVAL Val;
1445	} DBGFREGENTRY;
1446	/** Pointer to a register entry in a batch operation. */
1447	typedef DBGFREGENTRY *PDBGFREGENTRY;
1448	/** Pointer to a const register entry in a batch operation. */
1449	typedef DBGFREGENTRY const *PCDBGFREGENTRY;
1450
1451	/** Used with DBGFR3Reg* to indicate the hypervisor register set instead of the
1452	* guest. */
1453	#define DBGFREG_HYPER_VMCPUID UINT32_C(0x01000000)
1454
1455	VMMR3DECL(int) DBGFR3RegCpuQueryU8( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint8_t *pu8);
1456	VMMR3DECL(int) DBGFR3RegCpuQueryU16( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint16_t *pu16);
1457	VMMR3DECL(int) DBGFR3RegCpuQueryU32( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint32_t *pu32);
1458	VMMR3DECL(int) DBGFR3RegCpuQueryU64( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t *pu64);
1459	VMMR3DECL(int) DBGFR3RegCpuQueryU128(PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint128_t *pu128);
1460	VMMR3DECL(int) DBGFR3RegCpuQueryLrd( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, long double *plrd);
1461	VMMR3DECL(int) DBGFR3RegCpuQueryXdtr(PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t pu64Base, uint16_t pu16Limit);
1462	#if 0
1463	VMMR3DECL(int) DBGFR3RegCpuQueryBatch(PUVM pUVM,VMCPUID idCpu, PDBGFREGENTRY paRegs, size_t cRegs);
1464	VMMR3DECL(int) DBGFR3RegCpuQueryAll( PUVM pUVM, VMCPUID idCpu, PDBGFREGENTRY paRegs, size_t cRegs);
1465
1466	VMMR3DECL(int) DBGFR3RegCpuSetU8( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint8_t u8);
1467	VMMR3DECL(int) DBGFR3RegCpuSetU16( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint16_t u16);
1468	VMMR3DECL(int) DBGFR3RegCpuSetU32( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint32_t u32);
1469	VMMR3DECL(int) DBGFR3RegCpuSetU64( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t u64);
1470	VMMR3DECL(int) DBGFR3RegCpuSetU128( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint128_t u128);
1471	VMMR3DECL(int) DBGFR3RegCpuSetLrd( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, long double lrd);
1472	VMMR3DECL(int) DBGFR3RegCpuSetBatch( PUVM pUVM, VMCPUID idCpu, PCDBGFREGENTRY paRegs, size_t cRegs);
1473	#endif
1474
1475	VMMR3DECL(const char *) DBGFR3RegCpuName(PUVM pUVM, DBGFREG enmReg, DBGFREGVALTYPE enmType);
1476
1477	VMMR3_INT_DECL(int) DBGFR3RegRegisterCpu(PVM pVM, PVMCPU pVCpu, PCDBGFREGDESC paRegisters, bool fGuestRegs);
1478	VMMR3_INT_DECL(int) DBGFR3RegRegisterDevice(PVM pVM, PCDBGFREGDESC paRegisters, PPDMDEVINS pDevIns,
1479	const char *pszPrefix, uint32_t iInstance);
1480
1481	/**
1482	* Entry in a named batch query or set operation.
1483	*/
1484	typedef struct DBGFREGENTRYNM
1485	{
1486	/** The register name. */
1487	const char *pszName;
1488	/** The size of the value in bytes. */
1489	DBGFREGVALTYPE enmType;
1490	/** The register value. The valid view is indicated by enmType. */
1491	DBGFREGVAL Val;
1492	} DBGFREGENTRYNM;
1493	/** Pointer to a named register entry in a batch operation. */
1494	typedef DBGFREGENTRYNM *PDBGFREGENTRYNM;
1495	/** Pointer to a const named register entry in a batch operation. */
1496	typedef DBGFREGENTRYNM const *PCDBGFREGENTRYNM;
1497
1498	VMMR3DECL(int) DBGFR3RegNmValidate( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg);
1499
1500	VMMR3DECL(int) DBGFR3RegNmQuery( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PDBGFREGVAL pValue, PDBGFREGVALTYPE penmType);
1501	VMMR3DECL(int) DBGFR3RegNmQueryU8( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint8_t pu8);
1502	VMMR3DECL(int) DBGFR3RegNmQueryU16( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint16_t pu16);
1503	VMMR3DECL(int) DBGFR3RegNmQueryU32( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint32_t pu32);
1504	VMMR3DECL(int) DBGFR3RegNmQueryU64( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint64_t pu64);
1505	VMMR3DECL(int) DBGFR3RegNmQueryU128(PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PRTUINT128U pu128);
1506	/VMMR3DECL(int) DBGFR3RegNmQueryLrd( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, long double plrd);/
1507	VMMR3DECL(int) DBGFR3RegNmQueryXdtr(PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint64_t pu64Base, uint16_t *pu16Limit);
1508	VMMR3DECL(int) DBGFR3RegNmQueryBatch(PUVM pUVM,VMCPUID idDefCpu, PDBGFREGENTRYNM paRegs, size_t cRegs);
1509	VMMR3DECL(int) DBGFR3RegNmQueryAllCount(PUVM pUVM, size_t *pcRegs);
1510	VMMR3DECL(int) DBGFR3RegNmQueryAll( PUVM pUVM, PDBGFREGENTRYNM paRegs, size_t cRegs);
1511
1512	VMMR3DECL(int) DBGFR3RegNmSet( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType);
1513	VMMR3DECL(int) DBGFR3RegNmSetU8( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint8_t u8);
1514	VMMR3DECL(int) DBGFR3RegNmSetU16( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint16_t u16);
1515	VMMR3DECL(int) DBGFR3RegNmSetU32( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint32_t u32);
1516	VMMR3DECL(int) DBGFR3RegNmSetU64( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint64_t u64);
1517	VMMR3DECL(int) DBGFR3RegNmSetU128( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, RTUINT128U u128);
1518	VMMR3DECL(int) DBGFR3RegNmSetLrd( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, long double lrd);
1519	VMMR3DECL(int) DBGFR3RegNmSetBatch( PUVM pUVM, VMCPUID idDefCpu, PCDBGFREGENTRYNM paRegs, size_t cRegs);
1520
1521	/** @todo add enumeration methods. */
1522
1523	VMMR3DECL(int) DBGFR3RegPrintf( PUVM pUVM, VMCPUID idDefCpu, char pszBuf, size_t cbBuf, const char pszFormat, ...);
1524	VMMR3DECL(int) DBGFR3RegPrintfV(PUVM pUVM, VMCPUID idDefCpu, char pszBuf, size_t cbBuf, const char pszFormat, va_list va);
1525
1526
1527	/**
1528	* Guest OS digger interface identifier.
1529	*
1530	* This is for use together with PDBGFR3QueryInterface and is used to
1531	* obtain access to optional interfaces.
1532	*/
1533	typedef enum DBGFOSINTERFACE
1534	{
1535	/** The usual invalid entry. */
1536	DBGFOSINTERFACE_INVALID = 0,
1537	/** Process info. */
1538	DBGFOSINTERFACE_PROCESS,
1539	/** Thread info. */
1540	DBGFOSINTERFACE_THREAD,
1541	/** The end of the valid entries. */
1542	DBGFOSINTERFACE_END,
1543	/** The usual 32-bit type blowup. */
1544	DBGFOSINTERFACE_32BIT_HACK = 0x7fffffff
1545	} DBGFOSINTERFACE;
1546	/** Pointer to a Guest OS digger interface identifier. */
1547	typedef DBGFOSINTERFACE *PDBGFOSINTERFACE;
1548	/** Pointer to a const Guest OS digger interface identifier. */
1549	typedef DBGFOSINTERFACE const *PCDBGFOSINTERFACE;
1550
1551
1552	/**
1553	* Guest OS Digger Registration Record.
1554	*
1555	* This is used with the DBGFR3OSRegister() API.
1556	*/
1557	typedef struct DBGFOSREG
1558	{
1559	/** Magic value (DBGFOSREG_MAGIC). */
1560	uint32_t u32Magic;
1561	/** Flags. Reserved. */
1562	uint32_t fFlags;
1563	/** The size of the instance data. */
1564	uint32_t cbData;
1565	/** Operative System name. */
1566	char szName[24];
1567
1568	/**
1569	* Constructs the instance.
1570	*
1571	* @returns VBox status code.
1572	* @param pUVM The user mode VM handle.
1573	* @param pvData Pointer to the instance data.
1574	*/
1575	DECLCALLBACKMEMBER(int, pfnConstruct)(PUVM pUVM, void *pvData);
1576
1577	/**
1578	* Destroys the instance.
1579	*
1580	* @param pUVM The user mode VM handle.
1581	* @param pvData Pointer to the instance data.
1582	*/
1583	DECLCALLBACKMEMBER(void, pfnDestruct)(PUVM pUVM, void *pvData);
1584
1585	/**
1586	* Probes the guest memory for OS finger prints.
1587	*
1588	* No setup or so is performed, it will be followed by a call to pfnInit
1589	* or pfnRefresh that should take care of that.
1590	*
1591	* @returns true if is an OS handled by this module, otherwise false.
1592	* @param pUVM The user mode VM handle.
1593	* @param pvData Pointer to the instance data.
1594	*/
1595	DECLCALLBACKMEMBER(bool, pfnProbe)(PUVM pUVM, void *pvData);
1596
1597	/**
1598	* Initializes a fresly detected guest, loading symbols and such useful stuff.
1599	*
1600	* This is called after pfnProbe.
1601	*
1602	* @returns VBox status code.
1603	* @param pUVM The user mode VM handle.
1604	* @param pvData Pointer to the instance data.
1605	*/
1606	DECLCALLBACKMEMBER(int, pfnInit)(PUVM pUVM, void *pvData);
1607
1608	/**
1609	* Refreshes symbols and stuff following a redetection of the same OS.
1610	*
1611	* This is called after pfnProbe.
1612	*
1613	* @returns VBox status code.
1614	* @param pUVM The user mode VM handle.
1615	* @param pvData Pointer to the instance data.
1616	*/
1617	DECLCALLBACKMEMBER(int, pfnRefresh)(PUVM pUVM, void *pvData);
1618
1619	/**
1620	* Terminates an OS when a new (or none) OS has been detected,
1621	* and before destruction.
1622	*
1623	* This is called after pfnProbe and if needed before pfnDestruct.
1624	*
1625	* @param pUVM The user mode VM handle.
1626	* @param pvData Pointer to the instance data.
1627	*/
1628	DECLCALLBACKMEMBER(void, pfnTerm)(PUVM pUVM, void *pvData);
1629
1630	/**
1631	* Queries the version of the running OS.
1632	*
1633	* This is only called after pfnInit().
1634	*
1635	* @returns VBox status code.
1636	* @param pUVM The user mode VM handle.
1637	* @param pvData Pointer to the instance data.
1638	* @param pszVersion Where to store the version string.
1639	* @param cchVersion The size of the version string buffer.
1640	*/
1641	DECLCALLBACKMEMBER(int, pfnQueryVersion)(PUVM pUVM, void pvData, char pszVersion, size_t cchVersion);
1642
1643	/**
1644	* Queries the pointer to a interface.
1645	*
1646	* This is called after pfnProbe.
1647	*
1648	* @returns Pointer to the interface if available, NULL if not available.
1649	* @param pUVM The user mode VM handle.
1650	* @param pvData Pointer to the instance data.
1651	* @param enmIf The interface identifier.
1652	*/
1653	DECLCALLBACKMEMBER(void , pfnQueryInterface)(PUVM pUVM, void pvData, DBGFOSINTERFACE enmIf);
1654
1655	/** Trailing magic (DBGFOSREG_MAGIC). */
1656	uint32_t u32EndMagic;
1657	} DBGFOSREG;
1658	/** Pointer to a Guest OS digger registration record. */
1659	typedef DBGFOSREG *PDBGFOSREG;
1660	/** Pointer to a const Guest OS digger registration record. */
1661	typedef DBGFOSREG const *PCDBGFOSREG;
1662
1663	/** Magic value for DBGFOSREG::u32Magic and DBGFOSREG::u32EndMagic. (Hitomi Kanehara) */
1664	#define DBGFOSREG_MAGIC 0x19830808
1665
1666	VMMR3DECL(int) DBGFR3OSRegister(PUVM pUVM, PCDBGFOSREG pReg);
1667	VMMR3DECL(int) DBGFR3OSDeregister(PUVM pUVM, PCDBGFOSREG pReg);
1668	VMMR3DECL(int) DBGFR3OSDetect(PUVM pUVM, char *pszName, size_t cchName);
1669	VMMR3DECL(int) DBGFR3OSQueryNameAndVersion(PUVM pUVM, char pszName, size_t cchName, char pszVersion, size_t cchVersion);
1670	VMMR3DECL(void *) DBGFR3OSQueryInterface(PUVM pUVM, DBGFOSINTERFACE enmIf);
1671
1672
1673	VMMR3DECL(int) DBGFR3CoreWrite(PUVM pUVM, const char *pszFilename, bool fReplaceFile);
1674
1675	/** @} */
1676
1677
1678	RT_C_DECLS_END
1679
1680	#endif
1681

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

source: vbox/trunk/include/VBox/vmm/dbgf.h@ 47036

Download in other formats: