dbgf.h@ 94425

Last change on this file since 94425 was 93490, checked in by vboxsync, 3 years ago
vmm/dbgf.h: doxygen fix. bugref:10072
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 134.8 KB

Line
1	/** @file
2	* DBGF - Debugger Facility.
3	*/
4
5	/*
6	* Copyright (C) 2006-2022 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_INCLUDED_vmm_dbgf_h
27	#define VBOX_INCLUDED_vmm_dbgf_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <VBox/types.h>
33	#include <VBox/log.h> /* LOG_ENABLED */
34	#include <VBox/vmm/vmm.h>
35	#include <VBox/vmm/dbgfsel.h>
36
37	#include <iprt/stdarg.h>
38	#include <iprt/dbg.h>
39
40	RT_C_DECLS_BEGIN
41
42
43	/** @defgroup grp_dbgf The Debugger Facility API
44	* @ingroup grp_vmm
45	* @{
46	*/
47
48	/** @defgroup grp_dbgf_r0 The R0 DBGF API
49	* @{
50	*/
51	VMMR0_INT_DECL(void) DBGFR0InitPerVMData(PGVM pGVM);
52	VMMR0_INT_DECL(void) DBGFR0CleanupVM(PGVM pGVM);
53
54	/**
55	* Request buffer for DBGFR0TracerCreateReqHandler / VMMR0_DO_DBGF_TRACER_CREATE.
56	* @see DBGFR0TracerCreateReqHandler.
57	*/
58	typedef struct DBGFTRACERCREATEREQ
59	{
60	/** The header. */
61	SUPVMMR0REQHDR Hdr;
62	/** Out: Where to return the address of the ring-3 tracer instance. */
63	PDBGFTRACERINSR3 pTracerInsR3;
64
65	/** Number of bytes for the shared event ring buffer. */
66	uint32_t cbRingBuf;
67
68	/** Set if the raw-mode component is desired. */
69	bool fRCEnabled;
70	/** Explicit padding. */
71	bool afReserved[3];
72
73	} DBGFTRACERCREATEREQ;
74	/** Pointer to a DBGFR0TracerCreate / VMMR0_DO_DBGF_TRACER_CREATE request buffer. */
75	typedef DBGFTRACERCREATEREQ *PDBGFTRACERCREATEREQ;
76
77	VMMR0_INT_DECL(int) DBGFR0TracerCreateReqHandler(PGVM pGVM, PDBGFTRACERCREATEREQ pReq);
78
79	/**
80	* Request buffer for DBGFR0BpInitReqHandler / VMMR0_DO_DBGF_BP_INIT and
81	* DBGFR0BpPortIoInitReqHandler / VMMR0_DO_DBGF_BP_PORTIO_INIT.
82	* @see DBGFR0BpInitReqHandler, DBGFR0BpPortIoInitReqHandler.
83	*/
84	typedef struct DBGFBPINITREQ
85	{
86	/** The header. */
87	SUPVMMR0REQHDR Hdr;
88	/** Out: Ring-3 pointer of the L1 lookup table on success. */
89	R3PTRTYPE(volatile uint32_t *) paBpLocL1R3;
90	} DBGFBPINITREQ;
91	/** Pointer to a DBGFR0BpInitReqHandler / VMMR0_DO_DBGF_BP_INIT request buffer. */
92	typedef DBGFBPINITREQ *PDBGFBPINITREQ;
93
94	VMMR0_INT_DECL(int) DBGFR0BpInitReqHandler(PGVM pGVM, PDBGFBPINITREQ pReq);
95	VMMR0_INT_DECL(int) DBGFR0BpPortIoInitReqHandler(PGVM pGVM, PDBGFBPINITREQ pReq);
96
97	/**
98	* Request buffer for DBGFR0BpOwnerInitReqHandler / VMMR0_DO_DBGF_BP_OWNER_INIT.
99	* @see DBGFR0BpOwnerInitReqHandler.
100	*/
101	typedef struct DBGFBPOWNERINITREQ
102	{
103	/** The header. */
104	SUPVMMR0REQHDR Hdr;
105	/** Out: Ring-3 pointer of the breakpoint owner table on success. */
106	R3PTRTYPE(void *) paBpOwnerR3;
107	} DBGFBPOWNERINITREQ;
108	/** Pointer to a DBGFR0BpOwnerInitReqHandler / VMMR0_DO_DBGF_BP_INIT request buffer. */
109	typedef DBGFBPOWNERINITREQ *PDBGFBPOWNERINITREQ;
110
111	VMMR0_INT_DECL(int) DBGFR0BpOwnerInitReqHandler(PGVM pGVM, PDBGFBPOWNERINITREQ pReq);
112
113	/**
114	* Request buffer for DBGFR0BpChunkAllocReqHandler / VMMR0_DO_DBGF_CHUNK_ALLOC.
115	* @see DBGFR0BpChunkAllocReqHandler.
116	*/
117	typedef struct DBGFBPCHUNKALLOCREQ
118	{
119	/** The header. */
120	SUPVMMR0REQHDR Hdr;
121	/** Out: Ring-3 pointer of the chunk base on success. */
122	R3PTRTYPE(void *) pChunkBaseR3;
123
124	/** The chunk ID to allocate. */
125	uint32_t idChunk;
126	} DBGFBPCHUNKALLOCREQ;
127	/** Pointer to a DBGFR0BpChunkAllocReqHandler / VMMR0_DO_DBGF_CHUNK_ALLOC request buffer. */
128	typedef DBGFBPCHUNKALLOCREQ *PDBGFBPCHUNKALLOCREQ;
129
130	VMMR0_INT_DECL(int) DBGFR0BpChunkAllocReqHandler(PGVM pGVM, PDBGFBPCHUNKALLOCREQ pReq);
131
132	/**
133	* Request buffer for DBGFR0BpL2TblChunkAllocReqHandler / VMMR0_DO_DBGF_L2_TBL_CHUNK_ALLOC.
134	* @see DBGFR0BpL2TblChunkAllocReqHandler.
135	*/
136	typedef struct DBGFBPL2TBLCHUNKALLOCREQ
137	{
138	/** The header. */
139	SUPVMMR0REQHDR Hdr;
140	/** Out: Ring-3 pointer of the chunk base on success. */
141	R3PTRTYPE(void *) pChunkBaseR3;
142
143	/** The chunk ID to allocate. */
144	uint32_t idChunk;
145	} DBGFBPL2TBLCHUNKALLOCREQ;
146	/** Pointer to a DBGFR0BpChunkAllocReqHandler / VMMR0_DO_DBGF_L2_TBL_CHUNK_ALLOC request buffer. */
147	typedef DBGFBPL2TBLCHUNKALLOCREQ *PDBGFBPL2TBLCHUNKALLOCREQ;
148
149	VMMR0_INT_DECL(int) DBGFR0BpL2TblChunkAllocReqHandler(PGVM pGVM, PDBGFBPL2TBLCHUNKALLOCREQ pReq);
150	/** @} */
151
152
153	#ifdef IN_RING3
154
155	/**
156	* Mixed address.
157	*/
158	typedef struct DBGFADDRESS
159	{
160	/** The flat address. */
161	RTGCUINTPTR FlatPtr;
162	/** The selector offset address. */
163	RTGCUINTPTR off;
164	/** The selector. DBGF_SEL_FLAT is a legal value. */
165	RTSEL Sel;
166	/** Flags describing further details about the address. */
167	uint16_t fFlags;
168	} DBGFADDRESS;
169	/** Pointer to a mixed address. */
170	typedef DBGFADDRESS *PDBGFADDRESS;
171	/** Pointer to a const mixed address. */
172	typedef const DBGFADDRESS *PCDBGFADDRESS;
173
174	/** @name DBGFADDRESS Flags.
175	* @{ */
176	/** A 16:16 far address. */
177	#define DBGFADDRESS_FLAGS_FAR16 0
178	/** A 16:32 far address. */
179	#define DBGFADDRESS_FLAGS_FAR32 1
180	/** A 16:64 far address. */
181	#define DBGFADDRESS_FLAGS_FAR64 2
182	/** A flat address. */
183	#define DBGFADDRESS_FLAGS_FLAT 3
184	/** A physical address. */
185	#define DBGFADDRESS_FLAGS_PHYS 4
186	/** A ring-0 host address (internal use only). */
187	#define DBGFADDRESS_FLAGS_RING0 5
188	/** The address type mask. */
189	#define DBGFADDRESS_FLAGS_TYPE_MASK 7
190
191	/** Set if the address is valid. */
192	#define DBGFADDRESS_FLAGS_VALID RT_BIT(3)
193
194	/** Checks if the mixed address is flat or not. */
195	#define DBGFADDRESS_IS_FLAT(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FLAT )
196	/** Checks if the mixed address is flat or not. */
197	#define DBGFADDRESS_IS_PHYS(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_PHYS )
198	/** Checks if the mixed address is far 16:16 or not. */
199	#define DBGFADDRESS_IS_FAR16(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR16 )
200	/** Checks if the mixed address is far 16:32 or not. */
201	#define DBGFADDRESS_IS_FAR32(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR32 )
202	/** Checks if the mixed address is far 16:64 or not. */
203	#define DBGFADDRESS_IS_FAR64(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR64 )
204	/** Checks if the mixed address is any kind of far address. */
205	#define DBGFADDRESS_IS_FAR(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) <= DBGFADDRESS_FLAGS_FAR64 )
206	/** Checks if the mixed address host context ring-0 (special). */
207	#define DBGFADDRESS_IS_R0_HC(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_RING0 )
208	/** Checks if the mixed address a virtual guest context address (incl HMA). */
209	#define DBGFADDRESS_IS_VIRT_GC(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) <= DBGFADDRESS_FLAGS_FLAT )
210	/** Checks if the mixed address is valid. */
211	#define DBGFADDRESS_IS_VALID(pAddress) RT_BOOL((pAddress)->fFlags & DBGFADDRESS_FLAGS_VALID)
212	/** @} */
213
214	VMMR3DECL(int) DBGFR3AddrFromSelOff(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, RTSEL Sel, RTUINTPTR off);
215	VMMR3DECL(int) DBGFR3AddrFromSelInfoOff(PUVM pUVM, PDBGFADDRESS pAddress, PCDBGFSELINFO pSelInfo, RTUINTPTR off);
216	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromFlat(PUVM pUVM, PDBGFADDRESS pAddress, RTGCUINTPTR FlatPtr);
217	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromPhys(PUVM pUVM, PDBGFADDRESS pAddress, RTGCPHYS PhysAddr);
218	VMMR3_INT_DECL(PDBGFADDRESS) DBGFR3AddrFromHostR0(PDBGFADDRESS pAddress, RTR0UINTPTR R0Ptr);
219	VMMR3DECL(bool) DBGFR3AddrIsValid(PUVM pUVM, PCDBGFADDRESS pAddress);
220	VMMR3DECL(int) DBGFR3AddrToPhys(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, PRTGCPHYS pGCPhys);
221	VMMR3DECL(int) DBGFR3AddrToHostPhys(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, PRTHCPHYS pHCPhys);
222	VMMR3DECL(int) DBGFR3AddrToVolatileR3Ptr(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, bool fReadOnly, void **ppvR3Ptr);
223	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrAdd(PDBGFADDRESS pAddress, RTGCUINTPTR uAddend);
224	VMMR3DECL(PDBGFADDRESS) DBGFR3AddrSub(PDBGFADDRESS pAddress, RTGCUINTPTR uSubtrahend);
225
226	#endif /* IN_RING3 */
227
228
229
230	/**
231	* VMM Debug Event Type.
232	*/
233	typedef enum DBGFEVENTTYPE
234	{
235	/** Halt completed.
236	* This notifies that a halt command have been successfully completed.
237	*/
238	DBGFEVENT_HALT_DONE = 0,
239	/** Detach completed.
240	* This notifies that the detach command have been successfully completed.
241	*/
242	DBGFEVENT_DETACH_DONE,
243	/** The command from the debugger is not recognized.
244	* This means internal error or half implemented features.
245	*/
246	DBGFEVENT_INVALID_COMMAND,
247
248	/** Fatal error.
249	* This notifies a fatal error in the VMM and that the debugger get's a
250	* chance to first hand information about the the problem.
251	*/
252	DBGFEVENT_FATAL_ERROR,
253	/** Breakpoint Hit.
254	* This notifies that a breakpoint installed by the debugger was hit. The
255	* identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
256	*/
257	DBGFEVENT_BREAKPOINT,
258	/** I/O port breakpoint.
259	* @todo not yet implemented. */
260	DBGFEVENT_BREAKPOINT_IO,
261	/** MMIO breakpoint.
262	* @todo not yet implemented. */
263	DBGFEVENT_BREAKPOINT_MMIO,
264	/** Breakpoint Hit in the Hypervisor.
265	* This notifies that a breakpoint installed by the debugger was hit. The
266	* identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
267	* @todo raw-mode: remove this
268	*/
269	DBGFEVENT_BREAKPOINT_HYPER,
270	/** Assertion in the Hypervisor (breakpoint instruction).
271	* This notifies that a breakpoint instruction was hit in the hypervisor context.
272	*/
273	DBGFEVENT_ASSERTION_HYPER,
274	/** Single Stepped.
275	* This notifies that a single step operation was completed.
276	*/
277	DBGFEVENT_STEPPED,
278	/** Single Stepped.
279	* This notifies that a hypervisor single step operation was completed.
280	*/
281	DBGFEVENT_STEPPED_HYPER,
282	/** The developer have used the DBGFSTOP macro or the PDMDeviceDBGFSTOP function
283	* to bring up the debugger at a specific place.
284	*/
285	DBGFEVENT_DEV_STOP,
286	/** The VM is powering off.
287	* When this notification is received, the debugger thread should detach ASAP.
288	*/
289	DBGFEVENT_POWERING_OFF,
290
291	/** Hardware Interrupt break.
292	* @todo not yet implemented. */
293	DBGFEVENT_INTERRUPT_HARDWARE,
294	/** Software Interrupt break.
295	* @todo not yet implemented. */
296	DBGFEVENT_INTERRUPT_SOFTWARE,
297
298	/** The first selectable event.
299	* Whether the debugger wants or doesn't want these events can be configured
300	* via DBGFR3xxx and queried via DBGFR3yyy. */
301	DBGFEVENT_FIRST_SELECTABLE,
302	/** Tripple fault. */
303	DBGFEVENT_TRIPLE_FAULT = DBGFEVENT_FIRST_SELECTABLE,
304
305	/** @name Exception events
306	* The exception events normally represents guest exceptions, but depending on
307	* the execution mode some virtualization exceptions may occure (no nested
308	* paging, raw-mode, ++). When necessary, we will request additional VM exits.
309	* @{ */
310	DBGFEVENT_XCPT_FIRST, /*< The first exception event. /
311	DBGFEVENT_XCPT_DE /*< 0x00 - \#DE - Fault - NoErr - Integer divide error (zero/overflow). /
312	= DBGFEVENT_XCPT_FIRST,
313	DBGFEVENT_XCPT_DB, /*< 0x01 - \#DB - trap/fault - NoErr - debug event. /
314	DBGFEVENT_XCPT_02, /*< 0x02 - Reserved for NMI, see interrupt events. /
315	DBGFEVENT_XCPT_BP, /*< 0x03 - \#BP - Trap - NoErr - Breakpoint, INT 3 instruction. /
316	DBGFEVENT_XCPT_OF, /*< 0x04 - \#OF - Trap - NoErr - Overflow, INTO instruction. /
317	DBGFEVENT_XCPT_BR, /*< 0x05 - \#BR - Fault - NoErr - BOUND Range Exceeded, BOUND instruction. /
318	DBGFEVENT_XCPT_UD, /*< 0x06 - \#UD - Fault - NoErr - Undefined(/Invalid) Opcode. /
319	DBGFEVENT_XCPT_NM, /*< 0x07 - \#NM - Fault - NoErr - Device not available, FP or (F)WAIT instruction. /
320	DBGFEVENT_XCPT_DF, /*< 0x08 - \#DF - Abort - Err=0 - Double fault. /
321	DBGFEVENT_XCPT_09, /*< 0x09 - Int9 - Fault - NoErr - Coprocessor Segment Overrun (obsolete). /
322	DBGFEVENT_XCPT_TS, /*< 0x0a - \#TS - Fault - ErrCd - Invalid TSS, Taskswitch or TSS access. /
323	DBGFEVENT_XCPT_NP, /*< 0x0b - \#NP - Fault - ErrCd - Segment not present. /
324	DBGFEVENT_XCPT_SS, /*< 0x0c - \#SS - Fault - ErrCd - Stack-Segment fault. /
325	DBGFEVENT_XCPT_GP, /*< 0x0d - \#GP - Fault - ErrCd - General protection fault. /
326	DBGFEVENT_XCPT_PF, /*< 0x0e - \#PF - Fault - ErrCd - Page fault. - interrupt gate!!! /
327	DBGFEVENT_XCPT_0f, /*< 0x0f - Rsvd - Resvd - Resvd - Intel Reserved. /
328	DBGFEVENT_XCPT_MF, /*< 0x10 - \#MF - Fault - NoErr - x86 FPU Floating-Point Error (Math fault), FP or (F)WAIT instruction. /
329	DBGFEVENT_XCPT_AC, /*< 0x11 - \#AC - Fault - Err=0 - Alignment Check. /
330	DBGFEVENT_XCPT_MC, /*< 0x12 - \#MC - Abort - NoErr - Machine Check. /
331	DBGFEVENT_XCPT_XF, /*< 0x13 - \#XF - Fault - NoErr - SIMD Floating-Point Exception. /
332	DBGFEVENT_XCPT_VE, /*< 0x14 - \#VE - Fault - Noerr - Virtualization exception. /
333	DBGFEVENT_XCPT_15, /*< 0x15 - Intel Reserved. /
334	DBGFEVENT_XCPT_16, /*< 0x16 - Intel Reserved. /
335	DBGFEVENT_XCPT_17, /*< 0x17 - Intel Reserved. /
336	DBGFEVENT_XCPT_18, /*< 0x18 - Intel Reserved. /
337	DBGFEVENT_XCPT_19, /*< 0x19 - Intel Reserved. /
338	DBGFEVENT_XCPT_1a, /*< 0x1a - Intel Reserved. /
339	DBGFEVENT_XCPT_1b, /*< 0x1b - Intel Reserved. /
340	DBGFEVENT_XCPT_1c, /*< 0x1c - Intel Reserved. /
341	DBGFEVENT_XCPT_1d, /*< 0x1d - Intel Reserved. /
342	DBGFEVENT_XCPT_SX, /*< 0x1e - \#SX - Fault - ErrCd - Security Exception. /
343	DBGFEVENT_XCPT_1f, /*< 0x1f - Intel Reserved. /
344	DBGFEVENT_XCPT_LAST /*< The last exception event. /
345	= DBGFEVENT_XCPT_1f,
346	/** @} */
347
348	/** @name Instruction events
349	* The instruction events exerts all possible effort to intercept the
350	* relevant instructions. However, in some execution modes we won't be able
351	* to catch them. So it goes.
352	* @{ */
353	DBGFEVENT_INSTR_FIRST, /*< The first VM instruction event. /
354	DBGFEVENT_INSTR_HALT /*< Instruction: HALT /
355	= DBGFEVENT_INSTR_FIRST,
356	DBGFEVENT_INSTR_MWAIT, /*< Instruction: MWAIT /
357	DBGFEVENT_INSTR_MONITOR, /*< Instruction: MONITOR /
358	DBGFEVENT_INSTR_CPUID, /*< Instruction: CPUID (missing stuff in raw-mode). /
359	DBGFEVENT_INSTR_INVD, /*< Instruction: INVD /
360	DBGFEVENT_INSTR_WBINVD, /*< Instruction: WBINVD /
361	DBGFEVENT_INSTR_INVLPG, /*< Instruction: INVLPG /
362	DBGFEVENT_INSTR_RDTSC, /*< Instruction: RDTSC /
363	DBGFEVENT_INSTR_RDTSCP, /*< Instruction: RDTSCP /
364	DBGFEVENT_INSTR_RDPMC, /*< Instruction: RDPMC /
365	DBGFEVENT_INSTR_RDMSR, /*< Instruction: RDMSR /
366	DBGFEVENT_INSTR_WRMSR, /*< Instruction: WRMSR /
367	DBGFEVENT_INSTR_CRX_READ, /*< Instruction: CRx read instruction (missing smsw in raw-mode, and reads in general in VT-x). /
368	DBGFEVENT_INSTR_CRX_WRITE, /*< Instruction: CRx write /
369	DBGFEVENT_INSTR_DRX_READ, /*< Instruction: DRx read /
370	DBGFEVENT_INSTR_DRX_WRITE, /*< Instruction: DRx write /
371	DBGFEVENT_INSTR_PAUSE, /*< Instruction: PAUSE instruction (not in raw-mode). /
372	DBGFEVENT_INSTR_XSETBV, /*< Instruction: XSETBV /
373	DBGFEVENT_INSTR_SIDT, /*< Instruction: SIDT /
374	DBGFEVENT_INSTR_LIDT, /*< Instruction: LIDT /
375	DBGFEVENT_INSTR_SGDT, /*< Instruction: SGDT /
376	DBGFEVENT_INSTR_LGDT, /*< Instruction: LGDT /
377	DBGFEVENT_INSTR_SLDT, /*< Instruction: SLDT /
378	DBGFEVENT_INSTR_LLDT, /*< Instruction: LLDT /
379	DBGFEVENT_INSTR_STR, /*< Instruction: STR /
380	DBGFEVENT_INSTR_LTR, /*< Instruction: LTR /
381	DBGFEVENT_INSTR_GETSEC, /*< Instruction: GETSEC /
382	DBGFEVENT_INSTR_RSM, /*< Instruction: RSM /
383	DBGFEVENT_INSTR_RDRAND, /*< Instruction: RDRAND /
384	DBGFEVENT_INSTR_RDSEED, /*< Instruction: RDSEED /
385	DBGFEVENT_INSTR_XSAVES, /*< Instruction: XSAVES /
386	DBGFEVENT_INSTR_XRSTORS, /*< Instruction: XRSTORS /
387	DBGFEVENT_INSTR_VMM_CALL, /*< Instruction: VMCALL (intel) or VMMCALL (AMD) /
388	DBGFEVENT_INSTR_LAST_COMMON /*< Instruction: the last common event. /
389	= DBGFEVENT_INSTR_VMM_CALL,
390	DBGFEVENT_INSTR_VMX_FIRST, /*< Instruction: VT-x - First. /
391	DBGFEVENT_INSTR_VMX_VMCLEAR /*< Instruction: VT-x VMCLEAR /
392	= DBGFEVENT_INSTR_VMX_FIRST,
393	DBGFEVENT_INSTR_VMX_VMLAUNCH, /*< Instruction: VT-x VMLAUNCH /
394	DBGFEVENT_INSTR_VMX_VMPTRLD, /*< Instruction: VT-x VMPTRLD /
395	DBGFEVENT_INSTR_VMX_VMPTRST, /*< Instruction: VT-x VMPTRST /
396	DBGFEVENT_INSTR_VMX_VMREAD, /*< Instruction: VT-x VMREAD /
397	DBGFEVENT_INSTR_VMX_VMRESUME, /*< Instruction: VT-x VMRESUME /
398	DBGFEVENT_INSTR_VMX_VMWRITE, /*< Instruction: VT-x VMWRITE /
399	DBGFEVENT_INSTR_VMX_VMXOFF, /*< Instruction: VT-x VMXOFF /
400	DBGFEVENT_INSTR_VMX_VMXON, /*< Instruction: VT-x VMXON /
401	DBGFEVENT_INSTR_VMX_VMFUNC, /*< Instruction: VT-x VMFUNC /
402	DBGFEVENT_INSTR_VMX_INVEPT, /*< Instruction: VT-x INVEPT /
403	DBGFEVENT_INSTR_VMX_INVVPID, /*< Instruction: VT-x INVVPID /
404	DBGFEVENT_INSTR_VMX_INVPCID, /*< Instruction: VT-x INVPCID /
405	DBGFEVENT_INSTR_VMX_LAST /*< Instruction: VT-x - Last. /
406	= DBGFEVENT_INSTR_VMX_INVPCID,
407	DBGFEVENT_INSTR_SVM_FIRST, /*< Instruction: AMD-V - first /
408	DBGFEVENT_INSTR_SVM_VMRUN /*< Instruction: AMD-V VMRUN /
409	= DBGFEVENT_INSTR_SVM_FIRST,
410	DBGFEVENT_INSTR_SVM_VMLOAD, /*< Instruction: AMD-V VMLOAD /
411	DBGFEVENT_INSTR_SVM_VMSAVE, /*< Instruction: AMD-V VMSAVE /
412	DBGFEVENT_INSTR_SVM_STGI, /*< Instruction: AMD-V STGI /
413	DBGFEVENT_INSTR_SVM_CLGI, /*< Instruction: AMD-V CLGI /
414	DBGFEVENT_INSTR_SVM_LAST /*< Instruction: The last ADM-V VM exit event. /
415	= DBGFEVENT_INSTR_SVM_CLGI,
416	DBGFEVENT_INSTR_LAST /*< Instruction: The last instruction event. /
417	= DBGFEVENT_INSTR_SVM_LAST,
418	/** @} */
419
420
421	/** @name VM exit events.
422	* VM exits events for VT-x and AMD-V execution mode. Many of the VM exits
423	* behind these events are also directly translated into instruction events, but
424	* the difference here is that the exit events will not try provoke the exits.
425	* @{ */
426	DBGFEVENT_EXIT_FIRST, /*< The first VM exit event. /
427	DBGFEVENT_EXIT_TASK_SWITCH /*< Exit: Task switch. /
428	= DBGFEVENT_EXIT_FIRST,
429	DBGFEVENT_EXIT_HALT, /*< Exit: HALT instruction. /
430	DBGFEVENT_EXIT_MWAIT, /*< Exit: MWAIT instruction. /
431	DBGFEVENT_EXIT_MONITOR, /*< Exit: MONITOR instruction. /
432	DBGFEVENT_EXIT_CPUID, /*< Exit: CPUID instruction (missing stuff in raw-mode). /
433	DBGFEVENT_EXIT_INVD, /*< Exit: INVD instruction. /
434	DBGFEVENT_EXIT_WBINVD, /*< Exit: WBINVD instruction. /
435	DBGFEVENT_EXIT_INVLPG, /*< Exit: INVLPG instruction. /
436	DBGFEVENT_EXIT_RDTSC, /*< Exit: RDTSC instruction. /
437	DBGFEVENT_EXIT_RDTSCP, /*< Exit: RDTSCP instruction. /
438	DBGFEVENT_EXIT_RDPMC, /*< Exit: RDPMC instruction. /
439	DBGFEVENT_EXIT_RDMSR, /*< Exit: RDMSR instruction. /
440	DBGFEVENT_EXIT_WRMSR, /*< Exit: WRMSR instruction. /
441	DBGFEVENT_EXIT_CRX_READ, /*< Exit: CRx read instruction (missing smsw in raw-mode, and reads in general in VT-x). /
442	DBGFEVENT_EXIT_CRX_WRITE, /*< Exit: CRx write instruction. /
443	DBGFEVENT_EXIT_DRX_READ, /*< Exit: DRx read instruction. /
444	DBGFEVENT_EXIT_DRX_WRITE, /*< Exit: DRx write instruction. /
445	DBGFEVENT_EXIT_PAUSE, /*< Exit: PAUSE instruction (not in raw-mode). /
446	DBGFEVENT_EXIT_XSETBV, /*< Exit: XSETBV instruction. /
447	DBGFEVENT_EXIT_SIDT, /*< Exit: SIDT instruction. /
448	DBGFEVENT_EXIT_LIDT, /*< Exit: LIDT instruction. /
449	DBGFEVENT_EXIT_SGDT, /*< Exit: SGDT instruction. /
450	DBGFEVENT_EXIT_LGDT, /*< Exit: LGDT instruction. /
451	DBGFEVENT_EXIT_SLDT, /*< Exit: SLDT instruction. /
452	DBGFEVENT_EXIT_LLDT, /*< Exit: LLDT instruction. /
453	DBGFEVENT_EXIT_STR, /*< Exit: STR instruction. /
454	DBGFEVENT_EXIT_LTR, /*< Exit: LTR instruction. /
455	DBGFEVENT_EXIT_GETSEC, /*< Exit: GETSEC instruction. /
456	DBGFEVENT_EXIT_RSM, /*< Exit: RSM instruction. /
457	DBGFEVENT_EXIT_RDRAND, /*< Exit: RDRAND instruction. /
458	DBGFEVENT_EXIT_RDSEED, /*< Exit: RDSEED instruction. /
459	DBGFEVENT_EXIT_XSAVES, /*< Exit: XSAVES instruction. /
460	DBGFEVENT_EXIT_XRSTORS, /*< Exit: XRSTORS instruction. /
461	DBGFEVENT_EXIT_VMM_CALL, /*< Exit: VMCALL (intel) or VMMCALL (AMD) instruction. /
462	DBGFEVENT_EXIT_LAST_COMMON /*< Exit: the last common event. /
463	= DBGFEVENT_EXIT_VMM_CALL,
464	DBGFEVENT_EXIT_VMX_FIRST, /*< Exit: VT-x - First. /
465	DBGFEVENT_EXIT_VMX_VMCLEAR /*< Exit: VT-x VMCLEAR instruction. /
466	= DBGFEVENT_EXIT_VMX_FIRST,
467	DBGFEVENT_EXIT_VMX_VMLAUNCH, /*< Exit: VT-x VMLAUNCH instruction. /
468	DBGFEVENT_EXIT_VMX_VMPTRLD, /*< Exit: VT-x VMPTRLD instruction. /
469	DBGFEVENT_EXIT_VMX_VMPTRST, /*< Exit: VT-x VMPTRST instruction. /
470	DBGFEVENT_EXIT_VMX_VMREAD, /*< Exit: VT-x VMREAD instruction. /
471	DBGFEVENT_EXIT_VMX_VMRESUME, /*< Exit: VT-x VMRESUME instruction. /
472	DBGFEVENT_EXIT_VMX_VMWRITE, /*< Exit: VT-x VMWRITE instruction. /
473	DBGFEVENT_EXIT_VMX_VMXOFF, /*< Exit: VT-x VMXOFF instruction. /
474	DBGFEVENT_EXIT_VMX_VMXON, /*< Exit: VT-x VMXON instruction. /
475	DBGFEVENT_EXIT_VMX_VMFUNC, /*< Exit: VT-x VMFUNC instruction. /
476	DBGFEVENT_EXIT_VMX_INVEPT, /*< Exit: VT-x INVEPT instruction. /
477	DBGFEVENT_EXIT_VMX_INVVPID, /*< Exit: VT-x INVVPID instruction. /
478	DBGFEVENT_EXIT_VMX_INVPCID, /*< Exit: VT-x INVPCID instruction. /
479	DBGFEVENT_EXIT_VMX_EPT_VIOLATION, /*< Exit: VT-x EPT violation. /
480	DBGFEVENT_EXIT_VMX_EPT_MISCONFIG, /*< Exit: VT-x EPT misconfiguration. /
481	DBGFEVENT_EXIT_VMX_VAPIC_ACCESS, /*< Exit: VT-x Virtual APIC page access. /
482	DBGFEVENT_EXIT_VMX_VAPIC_WRITE, /*< Exit: VT-x Virtual APIC write. /
483	DBGFEVENT_EXIT_VMX_LAST /*< Exit: VT-x - Last. /
484	= DBGFEVENT_EXIT_VMX_VAPIC_WRITE,
485	DBGFEVENT_EXIT_SVM_FIRST, /*< Exit: AMD-V - first /
486	DBGFEVENT_EXIT_SVM_VMRUN /*< Exit: AMD-V VMRUN instruction. /
487	= DBGFEVENT_EXIT_SVM_FIRST,
488	DBGFEVENT_EXIT_SVM_VMLOAD, /*< Exit: AMD-V VMLOAD instruction. /
489	DBGFEVENT_EXIT_SVM_VMSAVE, /*< Exit: AMD-V VMSAVE instruction. /
490	DBGFEVENT_EXIT_SVM_STGI, /*< Exit: AMD-V STGI instruction. /
491	DBGFEVENT_EXIT_SVM_CLGI, /*< Exit: AMD-V CLGI instruction. /
492	DBGFEVENT_EXIT_SVM_LAST /*< Exit: The last ADM-V VM exit event. /
493	= DBGFEVENT_EXIT_SVM_CLGI,
494	DBGFEVENT_EXIT_LAST /*< Exit: The last VM exit event. /
495	= DBGFEVENT_EXIT_SVM_LAST,
496	/** @} */
497
498
499	/** @name Misc VT-x and AMD-V execution events.
500	* @{ */
501	DBGFEVENT_VMX_SPLIT_LOCK, /*< VT-x: Split-lock \#AC triggered by host having detection enabled. /
502	/** @} */
503
504
505	/** Access to an unassigned I/O port.
506	* @todo not yet implemented. */
507	DBGFEVENT_IOPORT_UNASSIGNED,
508	/** Access to an unused I/O port on a device.
509	* @todo not yet implemented. */
510	DBGFEVENT_IOPORT_UNUSED,
511	/** Unassigned memory event.
512	* @todo not yet implemented. */
513	DBGFEVENT_MEMORY_UNASSIGNED,
514	/** Attempt to write to unshadowed ROM.
515	* @todo not yet implemented. */
516	DBGFEVENT_MEMORY_ROM_WRITE,
517
518	/** Windows guest reported BSOD via hyperv MSRs. */
519	DBGFEVENT_BSOD_MSR,
520	/** Windows guest reported BSOD via EFI variables. */
521	DBGFEVENT_BSOD_EFI,
522	/** Windows guest reported BSOD via VMMDev. */
523	DBGFEVENT_BSOD_VMMDEV,
524
525	/** End of valid event values. */
526	DBGFEVENT_END,
527	/** The usual 32-bit hack. */
528	DBGFEVENT_32BIT_HACK = 0x7fffffff
529	} DBGFEVENTTYPE;
530	AssertCompile(DBGFEVENT_XCPT_LAST - DBGFEVENT_XCPT_FIRST == 0x1f);
531
532	/**
533	* The context of an event.
534	*/
535	typedef enum DBGFEVENTCTX
536	{
537	/** The usual invalid entry. */
538	DBGFEVENTCTX_INVALID = 0,
539	/** Raw mode. */
540	DBGFEVENTCTX_RAW,
541	/** Recompiled mode. */
542	DBGFEVENTCTX_REM,
543	/** VMX / AVT mode. */
544	DBGFEVENTCTX_HM,
545	/** Hypervisor context. */
546	DBGFEVENTCTX_HYPER,
547	/** Other mode */
548	DBGFEVENTCTX_OTHER,
549
550	/** The usual 32-bit hack */
551	DBGFEVENTCTX_32BIT_HACK = 0x7fffffff
552	} DBGFEVENTCTX;
553
554	/**
555	* VMM Debug Event.
556	*/
557	typedef struct DBGFEVENT
558	{
559	/** Type. */
560	DBGFEVENTTYPE enmType;
561	/** Context */
562	DBGFEVENTCTX enmCtx;
563	/** The vCPU/EMT which generated the event. */
564	VMCPUID idCpu;
565	/** Reserved. */
566	uint32_t uReserved;
567	/** Type specific data. */
568	union
569	{
570	/** Fatal error details. */
571	struct
572	{
573	/** The GC return code. */
574	int rc;
575	} FatalError;
576
577	/** Source location. */
578	struct
579	{
580	/** File name. */
581	R3PTRTYPE(const char *) pszFile;
582	/** Function name. */
583	R3PTRTYPE(const char *) pszFunction;
584	/** Message. */
585	R3PTRTYPE(const char *) pszMessage;
586	/** Line number. */
587	unsigned uLine;
588	} Src;
589
590	/** Assertion messages. */
591	struct
592	{
593	/** The first message. */
594	R3PTRTYPE(const char *) pszMsg1;
595	/** The second message. */
596	R3PTRTYPE(const char *) pszMsg2;
597	} Assert;
598
599	/** Breakpoint. */
600	struct DBGFEVENTBP
601	{
602	/** The handle of the breakpoint which was hit. */
603	DBGFBP hBp;
604	} Bp;
605
606	/** Generic debug event. */
607	struct DBGFEVENTGENERIC
608	{
609	/** Number of arguments. */
610	uint8_t cArgs;
611	/** Alignment padding. */
612	uint8_t uPadding[7];
613	/** Arguments. */
614	uint64_t auArgs[5];
615	} Generic;
616
617	/** Padding for ensuring that the structure is 8 byte aligned. */
618	uint64_t au64Padding[6];
619	} u;
620	} DBGFEVENT;
621	AssertCompileSizeAlignment(DBGFEVENT, 8);
622	AssertCompileSize(DBGFEVENT, 64);
623	/** Pointer to VMM Debug Event. */
624	typedef DBGFEVENT *PDBGFEVENT;
625	/** Pointer to const VMM Debug Event. */
626	typedef const DBGFEVENT *PCDBGFEVENT;
627
628	#ifdef IN_RING3 /* The event API only works in ring-3. */
629
630	/** @def DBGFSTOP
631	* Stops the debugger raising a DBGFEVENT_DEVELOPER_STOP event.
632	*
633	* @returns VBox status code which must be propagated up to EM if not VINF_SUCCESS.
634	* @param pVM The cross context VM structure.
635	*/
636	# ifdef VBOX_STRICT
637	# define DBGFSTOP(pVM) DBGFR3EventSrc(pVM, DBGFEVENT_DEV_STOP, __FILE__, __LINE__, __PRETTY_FUNCTION__, NULL)
638	# else
639	# define DBGFSTOP(pVM) VINF_SUCCESS
640	# endif
641
642	VMMR3_INT_DECL(int) DBGFR3Init(PVM pVM);
643	VMMR3_INT_DECL(int) DBGFR3Term(PVM pVM);
644	VMMR3DECL(void) DBGFR3TermUVM(PUVM pUVM);
645	VMMR3_INT_DECL(void) DBGFR3PowerOff(PVM pVM);
646	VMMR3_INT_DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta);
647
648	VMMR3_INT_DECL(int) DBGFR3VMMForcedAction(PVM pVM, PVMCPU pVCpu);
649	VMMR3_INT_DECL(VBOXSTRICTRC) DBGFR3EventHandlePending(PVM pVM, PVMCPU pVCpu);
650	VMMR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent);
651	VMMR3DECL(int) DBGFR3EventSrc(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine,
652	const char pszFunction, const char pszFormat, ...) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 7);
653	VMMR3DECL(int) DBGFR3EventSrcV(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszFile, unsigned uLine,
654	const char pszFunction, const char pszFormat, va_list args) RT_IPRT_FORMAT_ATTR_MAYBE_NULL(6, 0);
655	VMMR3_INT_DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszMsg1, const char pszMsg2);
656	VMMR3_INT_DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent);
657
658	VMMR3_INT_DECL(int) DBGFR3PrgStep(PVMCPU pVCpu);
659
660	VMMR3DECL(int) DBGFR3Attach(PUVM pUVM);
661	VMMR3DECL(int) DBGFR3Detach(PUVM pUVM);
662	VMMR3DECL(int) DBGFR3EventWait(PUVM pUVM, RTMSINTERVAL cMillies, PDBGFEVENT pEvent);
663	VMMR3DECL(int) DBGFR3Halt(PUVM pUVM, VMCPUID idCpu);
664	VMMR3DECL(bool) DBGFR3IsHalted(PUVM pUVM, VMCPUID idCpu);
665	VMMR3DECL(int) DBGFR3QueryWaitable(PUVM pUVM);
666	VMMR3DECL(int) DBGFR3Resume(PUVM pUVM, VMCPUID idCpu);
667	VMMR3DECL(int) DBGFR3InjectNMI(PUVM pUVM, VMCPUID idCpu);
668	VMMR3DECL(int) DBGFR3Step(PUVM pUVM, VMCPUID idCpu);
669	VMMR3DECL(int) DBGFR3StepEx(PUVM pUVM, VMCPUID idCpu, uint32_t fFlags, PCDBGFADDRESS pStopPcAddr,
670	PCDBGFADDRESS pStopPopAddr, RTGCUINTPTR cbStopPop, uint32_t cMaxSteps);
671
672	/** @name DBGF_STEP_F_XXX - Flags for DBGFR3StepEx.
673	*
674	* @note The stop filters are not applied to the starting instruction.
675	*
676	* @{ */
677	/** Step into CALL, INT, SYSCALL and SYSENTER instructions. */
678	#define DBGF_STEP_F_INTO RT_BIT_32(0)
679	/** Step over CALL, INT, SYSCALL and SYSENTER instruction when considering
680	* what's "next". */
681	#define DBGF_STEP_F_OVER RT_BIT_32(1)
682
683	/** Stop on the next CALL, INT, SYSCALL, SYSENTER instruction. */
684	#define DBGF_STEP_F_STOP_ON_CALL RT_BIT_32(8)
685	/** Stop on the next RET, IRET, SYSRET, SYSEXIT instruction. */
686	#define DBGF_STEP_F_STOP_ON_RET RT_BIT_32(9)
687	/** Stop after the next RET, IRET, SYSRET, SYSEXIT instruction. */
688	#define DBGF_STEP_F_STOP_AFTER_RET RT_BIT_32(10)
689	/** Stop on the given address.
690	* The comparison will be made using effective (flat) addresses. */
691	#define DBGF_STEP_F_STOP_ON_ADDRESS RT_BIT_32(11)
692	/** Stop when the stack pointer pops to or past the given address.
693	* The comparison will be made using effective (flat) addresses. */
694	#define DBGF_STEP_F_STOP_ON_STACK_POP RT_BIT_32(12)
695	/** Mask of stop filter flags. */
696	#define DBGF_STEP_F_STOP_FILTER_MASK UINT32_C(0x00001f00)
697
698	/** Mask of valid flags. */
699	#define DBGF_STEP_F_VALID_MASK UINT32_C(0x00001f03)
700	/** @} */
701
702	/**
703	* Event configuration array element, see DBGFR3EventConfigEx.
704	*/
705	typedef struct DBGFEVENTCONFIG
706	{
707	/** The event to configure */
708	DBGFEVENTTYPE enmType;
709	/** The new state. */
710	bool fEnabled;
711	/** Unused. */
712	uint8_t abUnused[3];
713	} DBGFEVENTCONFIG;
714	/** Pointer to an event config. */
715	typedef DBGFEVENTCONFIG *PDBGFEVENTCONFIG;
716	/** Pointer to a const event config. */
717	typedef const DBGFEVENTCONFIG *PCDBGFEVENTCONFIG;
718
719	VMMR3DECL(int) DBGFR3EventConfigEx(PUVM pUVM, PCDBGFEVENTCONFIG paConfigs, size_t cConfigs);
720	VMMR3DECL(int) DBGFR3EventConfig(PUVM pUVM, DBGFEVENTTYPE enmEvent, bool fEnabled);
721	VMMR3DECL(bool) DBGFR3EventIsEnabled(PUVM pUVM, DBGFEVENTTYPE enmEvent);
722	VMMR3DECL(int) DBGFR3EventQuery(PUVM pUVM, PDBGFEVENTCONFIG paConfigs, size_t cConfigs);
723
724	/** @name DBGFINTERRUPTSTATE_XXX - interrupt break state.
725	* @{ */
726	#define DBGFINTERRUPTSTATE_DISABLED 0
727	#define DBGFINTERRUPTSTATE_ENABLED 1
728	#define DBGFINTERRUPTSTATE_DONT_TOUCH 2
729	/** @} */
730
731	/**
732	* Interrupt break state configuration entry.
733	*/
734	typedef struct DBGFINTERRUPTCONFIG
735	{
736	/** The interrupt number. */
737	uint8_t iInterrupt;
738	/** The hardware interrupt state (DBGFINTERRUPTSTATE_XXX). */
739	uint8_t enmHardState;
740	/** The software interrupt state (DBGFINTERRUPTSTATE_XXX). */
741	uint8_t enmSoftState;
742	} DBGFINTERRUPTCONFIG;
743	/** Pointer to an interrupt break state config entyr. */
744	typedef DBGFINTERRUPTCONFIG *PDBGFINTERRUPTCONFIG;
745	/** Pointer to a const interrupt break state config entyr. */
746	typedef DBGFINTERRUPTCONFIG const *PCDBGFINTERRUPTCONFIG;
747
748	VMMR3DECL(int) DBGFR3InterruptConfigEx(PUVM pUVM, PCDBGFINTERRUPTCONFIG paConfigs, size_t cConfigs);
749	VMMR3DECL(int) DBGFR3InterruptHardwareConfig(PUVM pUVM, uint8_t iInterrupt, bool fEnabled);
750	VMMR3DECL(int) DBGFR3InterruptSoftwareConfig(PUVM pUVM, uint8_t iInterrupt, bool fEnabled);
751	VMMR3DECL(int) DBGFR3InterruptHardwareIsEnabled(PUVM pUVM, uint8_t iInterrupt);
752	VMMR3DECL(int) DBGFR3InterruptSoftwareIsEnabled(PUVM pUVM, uint8_t iInterrupt);
753
754	#endif /* IN_RING3 */
755
756	/** @def DBGF_IS_EVENT_ENABLED
757	* Checks if a selectable debug event is enabled or not (fast).
758	*
759	* @returns true/false.
760	* @param a_pVM Pointer to the cross context VM structure.
761	* @param a_enmEvent The selectable event to check.
762	* @remarks Only for use internally in the VMM. Use DBGFR3EventIsEnabled elsewhere.
763	*/
764	#if defined(VBOX_STRICT) && defined(RT_COMPILER_SUPPORTS_LAMBDA)
765	# define DBGF_IS_EVENT_ENABLED(a_pVM, a_enmEvent) \
766	([](PVM a_pLambdaVM, DBGFEVENTTYPE a_enmLambdaEvent) -> bool { \
767	Assert( a_enmLambdaEvent >= DBGFEVENT_FIRST_SELECTABLE \
768	\|\| a_enmLambdaEvent == DBGFEVENT_INTERRUPT_HARDWARE \
769	\|\| a_enmLambdaEvent == DBGFEVENT_INTERRUPT_SOFTWARE); \
770	Assert(a_enmLambdaEvent < DBGFEVENT_END); \
771	return ASMBitTest(&a_pLambdaVM->dbgf.ro.bmSelectedEvents, a_enmLambdaEvent); \
772	}(a_pVM, a_enmEvent))
773	#elif defined(VBOX_STRICT) && defined(__GNUC__)
774	# define DBGF_IS_EVENT_ENABLED(a_pVM, a_enmEvent) \
775	__extension__ ({ \
776	Assert( (a_enmEvent) >= DBGFEVENT_FIRST_SELECTABLE \
777	\|\| (a_enmEvent) == DBGFEVENT_INTERRUPT_HARDWARE \
778	\|\| (a_enmEvent) == DBGFEVENT_INTERRUPT_SOFTWARE); \
779	Assert((a_enmEvent) < DBGFEVENT_END); \
780	ASMBitTest(&(a_pVM)->dbgf.ro.bmSelectedEvents, (a_enmEvent)); \
781	})
782	#else
783	# define DBGF_IS_EVENT_ENABLED(a_pVM, a_enmEvent) \
784	ASMBitTest(&(a_pVM)->dbgf.ro.bmSelectedEvents, (a_enmEvent))
785	#endif
786
787
788	/** @def DBGF_IS_HARDWARE_INT_ENABLED
789	* Checks if hardware interrupt interception is enabled or not for an interrupt.
790	*
791	* @returns true/false.
792	* @param a_pVM Pointer to the cross context VM structure.
793	* @param a_iInterrupt Interrupt to check.
794	* @remarks Only for use internally in the VMM. Use
795	* DBGFR3InterruptHardwareIsEnabled elsewhere.
796	*/
797	#define DBGF_IS_HARDWARE_INT_ENABLED(a_pVM, a_iInterrupt) \
798	ASMBitTest(&(a_pVM)->dbgf.ro.bmHardIntBreakpoints, (uint8_t)(a_iInterrupt))
799
800	/** @def DBGF_IS_SOFTWARE_INT_ENABLED
801	* Checks if software interrupt interception is enabled or not for an interrupt.
802	*
803	* @returns true/false.
804	* @param a_pVM Pointer to the cross context VM structure.
805	* @param a_iInterrupt Interrupt to check.
806	* @remarks Only for use internally in the VMM. Use
807	* DBGFR3InterruptSoftwareIsEnabled elsewhere.
808	*/
809	#define DBGF_IS_SOFTWARE_INT_ENABLED(a_pVM, a_iInterrupt) \
810	ASMBitTest(&(a_pVM)->dbgf.ro.bmSoftIntBreakpoints, (uint8_t)(a_iInterrupt))
811
812
813
814	/** Breakpoint type. */
815	typedef enum DBGFBPTYPE
816	{
817	/** Invalid breakpoint type. */
818	DBGFBPTYPE_INVALID = 0,
819	/** Debug register. */
820	DBGFBPTYPE_REG,
821	/** INT 3 instruction. */
822	DBGFBPTYPE_INT3,
823	/** Port I/O breakpoint. */
824	DBGFBPTYPE_PORT_IO,
825	/** Memory mapped I/O breakpoint. */
826	DBGFBPTYPE_MMIO,
827	/** ensure 32-bit size. */
828	DBGFBPTYPE_32BIT_HACK = 0x7fffffff
829	} DBGFBPTYPE;
830
831
832	/** @name DBGFBPIOACCESS_XXX - I/O (port + mmio) access types.
833	* @{ */
834	/** Byte sized read accesses. */
835	#define DBGFBPIOACCESS_READ_BYTE UINT32_C(0x00000001)
836	/** Word sized accesses. */
837	#define DBGFBPIOACCESS_READ_WORD UINT32_C(0x00000002)
838	/** Double word sized accesses. */
839	#define DBGFBPIOACCESS_READ_DWORD UINT32_C(0x00000004)
840	/** Quad word sized accesses - not available for I/O ports. */
841	#define DBGFBPIOACCESS_READ_QWORD UINT32_C(0x00000008)
842	/** Other sized accesses - not available for I/O ports. */
843	#define DBGFBPIOACCESS_READ_OTHER UINT32_C(0x00000010)
844	/** Read mask. */
845	#define DBGFBPIOACCESS_READ_MASK UINT32_C(0x0000001f)
846
847	/** Byte sized write accesses. */
848	#define DBGFBPIOACCESS_WRITE_BYTE UINT32_C(0x00000100)
849	/** Word sized write accesses. */
850	#define DBGFBPIOACCESS_WRITE_WORD UINT32_C(0x00000200)
851	/** Double word sized write accesses. */
852	#define DBGFBPIOACCESS_WRITE_DWORD UINT32_C(0x00000400)
853	/** Quad word sized write accesses - not available for I/O ports. */
854	#define DBGFBPIOACCESS_WRITE_QWORD UINT32_C(0x00000800)
855	/** Other sized write accesses - not available for I/O ports. */
856	#define DBGFBPIOACCESS_WRITE_OTHER UINT32_C(0x00001000)
857	/** Write mask. */
858	#define DBGFBPIOACCESS_WRITE_MASK UINT32_C(0x00001f00)
859
860	/** All kind of access (read, write, all sizes). */
861	#define DBGFBPIOACCESS_ALL UINT32_C(0x00001f1f)
862	/** All kind of access for MMIO (read, write, all sizes). */
863	#define DBGFBPIOACCESS_ALL_MMIO DBGFBPIOACCESS_ALL
864	/** All kind of access (read, write, all sizes). */
865	#define DBGFBPIOACCESS_ALL_PORT_IO UINT32_C(0x00000303)
866
867	/** The acceptable mask for I/O ports. */
868	#define DBGFBPIOACCESS_VALID_MASK_PORT_IO UINT32_C(0x00000303)
869	/** The acceptable mask for MMIO. */
870	#define DBGFBPIOACCESS_VALID_MASK_MMIO UINT32_C(0x00001f1f)
871	/** @} */
872
873	/**
874	* The visible breakpoint state (read-only).
875	*/
876	typedef struct DBGFBPPUB
877	{
878	/** The number of breakpoint hits. */
879	uint64_t cHits;
880	/** The hit number which starts to trigger the breakpoint. */
881	uint64_t iHitTrigger;
882	/** The hit number which stops triggering the breakpoint (disables it).
883	* Use ~(uint64_t)0 if it should never stop. */
884	uint64_t iHitDisable;
885	/** The breakpoint owner handle (a nil owner defers the breakpoint to the
886	* debugger). */
887	DBGFBPOWNER hOwner;
888	/** Breakpoint type stored as a 16bit integer to stay within size limits. */
889	uint16_t u16Type;
890	/** Breakpoint flags. */
891	uint16_t fFlags;
892
893	/** Union of type specific data. */
894	union
895	{
896	/** The flat GC address breakpoint address for REG and INT3 breakpoints. */
897	RTGCUINTPTR GCPtr;
898
899	/** Debug register data. */
900	struct DBGFBPREG
901	{
902	/** The flat GC address of the breakpoint. */
903	RTGCUINTPTR GCPtr;
904	/** The debug register number. */
905	uint8_t iReg;
906	/** The access type (one of the X86_DR7_RW_* value). */
907	uint8_t fType;
908	/** The access size. */
909	uint8_t cb;
910	} Reg;
911
912	/** INT3 breakpoint data. */
913	struct DBGFBPINT3
914	{
915	/** The flat GC address of the breakpoint. */
916	RTGCUINTPTR GCPtr;
917	/** The physical address of the breakpoint. */
918	RTGCPHYS PhysAddr;
919	/** The byte value we replaced by the INT 3 instruction. */
920	uint8_t bOrg;
921	} Int3;
922
923	/** I/O port breakpoint data. */
924	struct DBGFBPPORTIO
925	{
926	/** The first port. */
927	RTIOPORT uPort;
928	/** The number of ports. */
929	RTIOPORT cPorts;
930	/** Valid DBGFBPIOACCESS_XXX selection, max DWORD size. */
931	uint32_t fAccess;
932	} PortIo;
933
934	/** Memory mapped I/O breakpoint data. */
935	struct DBGFBPMMIO
936	{
937	/** The first MMIO address. */
938	RTGCPHYS PhysAddr;
939	/** The size of the MMIO range in bytes. */
940	uint32_t cb;
941	/** Valid DBGFBPIOACCESS_XXX selection, max QWORD size. */
942	uint32_t fAccess;
943	} Mmio;
944
945	/** Padding to the anticipated size. */
946	uint64_t u64Padding[3];
947	} u;
948	} DBGFBPPUB;
949	AssertCompileSize(DBGFBPPUB, 64 - 8);
950	AssertCompileMembersAtSameOffset(DBGFBPPUB, u.GCPtr, DBGFBPPUB, u.Reg.GCPtr);
951	AssertCompileMembersAtSameOffset(DBGFBPPUB, u.GCPtr, DBGFBPPUB, u.Int3.GCPtr);
952
953	/** Pointer to the visible breakpoint state. */
954	typedef DBGFBPPUB *PDBGFBPPUB;
955	/** Pointer to a const visible breakpoint state. */
956	typedef const DBGFBPPUB *PCDBGFBPPUB;
957
958	/** Sets the DBGFPUB::u16Type member. */
959	#define DBGF_BP_PUB_MAKE_TYPE(a_enmType) ((uint16_t)(a_enmType))
960	/** Returns the type of the DBGFPUB::u16Type member. */
961	#define DBGF_BP_PUB_GET_TYPE(a_pBp) ((DBGFBPTYPE)((a_pBp)->u16Type))
962	/** Returns the enabled status of DBGFPUB::fFlags member. */
963	#define DBGF_BP_PUB_IS_ENABLED(a_pBp) RT_BOOL((a_pBp)->fFlags & DBGF_BP_F_ENABLED)
964	/** Returns whether DBGF_BP_F_HIT_EXEC_BEFORE is set for DBGFPUB::fFlags. */
965	#define DBGF_BP_PUB_IS_EXEC_BEFORE(a_pBp) RT_BOOL((a_pBp)->fFlags & DBGF_BP_F_HIT_EXEC_BEFORE)
966	/** Returns whether DBGF_BP_F_HIT_EXEC_AFTER is set for DBGFPUB::fFlags. */
967	#define DBGF_BP_PUB_IS_EXEC_AFTER(a_pBp) RT_BOOL((a_pBp)->fFlags & DBGF_BP_F_HIT_EXEC_AFTER)
968
969
970	/** @name Possible DBGFBPPUB::fFlags flags.
971	* @{ */
972	/** Default flags, breakpoint is enabled and hits before the instruction is executed. */
973	#define DBGF_BP_F_DEFAULT (DBGF_BP_F_ENABLED \| DBGF_BP_F_HIT_EXEC_BEFORE)
974	/** Flag whether the breakpoint is enabled currently. */
975	#define DBGF_BP_F_ENABLED RT_BIT(0)
976	/** Flag indicating whether the action assoicated with the breakpoint should be carried out
977	* before the instruction causing the breakpoint to hit was executed. */
978	#define DBGF_BP_F_HIT_EXEC_BEFORE RT_BIT(1)
979	/** Flag indicating whether the action assoicated with the breakpoint should be carried out
980	* after the instruction causing the breakpoint to hit was executed. */
981	#define DBGF_BP_F_HIT_EXEC_AFTER RT_BIT(2)
982	/** The acceptable flags mask. */
983	#define DBGF_BP_F_VALID_MASK UINT32_C(0x00000007)
984	/** @} */
985
986
987	/**
988	* Breakpoint hit handler.
989	*
990	* @returns Strict VBox status code.
991	* @retval VINF_SUCCESS if the breakpoint was handled and guest execution can resume.
992	* @retval VINF_DBGF_BP_HALT if guest execution should be stopped and the debugger should be invoked.
993	* @retval VINF_DBGF_R3_BP_OWNER_DEFER return to ring-3 and invoke the owner callback there again.
994	*
995	* @param pVM The cross-context VM structure pointer.
996	* @param idCpu ID of the vCPU triggering the breakpoint.
997	* @param pvUserBp User argument of the set breakpoint.
998	* @param hBp The breakpoint handle.
999	* @param pBpPub Pointer to the readonly public state of the breakpoint.
1000	* @param fFlags Flags indicating when the handler was called (DBGF_BP_F_HIT_EXEC_BEFORE vs DBGF_BP_F_HIT_EXEC_AFTER).
1001	*
1002	* @remarks The handler is called on the EMT of vCPU triggering the breakpoint and no locks are held.
1003	* @remarks Any status code returned other than the ones mentioned will send the VM straight into a
1004	* guru meditation.
1005	*/
1006	typedef DECLCALLBACKTYPE(VBOXSTRICTRC, FNDBGFBPHIT,(PVM pVM, VMCPUID idCpu, void *pvUserBp, DBGFBP hBp, PCDBGFBPPUB pBpPub,
1007	uint16_t fFlags));
1008	/** Pointer to a FNDBGFBPHIT(). */
1009	typedef FNDBGFBPHIT *PFNDBGFBPHIT;
1010
1011
1012	/**
1013	* I/O breakpoint hit handler.
1014	*
1015	* @returns Strict VBox status code.
1016	* @retval VINF_SUCCESS if the breakpoint was handled and guest execution can resume.
1017	* @retval VINF_DBGF_BP_HALT if guest execution should be stopped and the debugger should be invoked.
1018	* @retval VINF_DBGF_R3_BP_OWNER_DEFER return to ring-3 and invoke the owner callback there again.
1019	*
1020	* @param pVM The cross-context VM structure pointer.
1021	* @param idCpu ID of the vCPU triggering the breakpoint.
1022	* @param pvUserBp User argument of the set breakpoint.
1023	* @param hBp The breakpoint handle.
1024	* @param pBpPub Pointer to the readonly public state of the breakpoint.
1025	* @param fFlags Flags indicating when the handler was called (DBGF_BP_F_HIT_EXEC_BEFORE vs DBGF_BP_F_HIT_EXEC_AFTER).
1026	* @param fAccess Access flags, see DBGFBPIOACCESS_XXX.
1027	* @param uAddr The address of the access, for port I/O this will hold the port number.
1028	* @param uValue The value read or written (the value for reads is only valid when DBGF_BP_F_HIT_EXEC_AFTER is set).
1029	*
1030	* @remarks The handler is called on the EMT of vCPU triggering the breakpoint and no locks are held.
1031	* @remarks Any status code returned other than the ones mentioned will send the VM straight into a
1032	* guru meditation.
1033	*/
1034	typedef DECLCALLBACKTYPE(VBOXSTRICTRC, FNDBGFBPIOHIT,(PVM pVM, VMCPUID idCpu, void *pvUserBp, DBGFBP hBp, PCDBGFBPPUB pBpPub,
1035	uint16_t fFlags, uint32_t fAccess, uint64_t uAddr, uint64_t uValue));
1036	/** Pointer to a FNDBGFBPIOHIT(). */
1037	typedef FNDBGFBPIOHIT *PFNDBGFBPIOHIT;
1038
1039
1040	#ifdef IN_RING3
1041	/** @defgroup grp_dbgf_bp_r3 The DBGF Breakpoint Host Context Ring-3 API
1042	* @{ */
1043	VMMR3DECL(int) DBGFR3BpOwnerCreate(PUVM pUVM, PFNDBGFBPHIT pfnBpHit, PFNDBGFBPIOHIT pfnBpIoHit, PDBGFBPOWNER phBpOwner);
1044	VMMR3DECL(int) DBGFR3BpOwnerDestroy(PUVM pUVM, DBGFBPOWNER hBpOwner);
1045
1046	VMMR3DECL(int) DBGFR3BpSetInt3(PUVM pUVM, VMCPUID idSrcCpu, PCDBGFADDRESS pAddress,
1047	uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1048	VMMR3DECL(int) DBGFR3BpSetInt3Ex(PUVM pUVM, DBGFBPOWNER hOwner, void *pvUser,
1049	VMCPUID idSrcCpu, PCDBGFADDRESS pAddress, uint16_t fFlags,
1050	uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1051	VMMR3DECL(int) DBGFR3BpSetReg(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger,
1052	uint64_t iHitDisable, uint8_t fType, uint8_t cb, PDBGFBP phBp);
1053	VMMR3DECL(int) DBGFR3BpSetRegEx(PUVM pUVM, DBGFBPOWNER hOwner, void *pvUser,
1054	PCDBGFADDRESS pAddress, uint16_t fFlags,
1055	uint64_t iHitTrigger, uint64_t iHitDisable,
1056	uint8_t fType, uint8_t cb, PDBGFBP phBp);
1057	VMMR3DECL(int) DBGFR3BpSetREM(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger,
1058	uint64_t iHitDisable, PDBGFBP phBp);
1059	VMMR3DECL(int) DBGFR3BpSetPortIo(PUVM pUVM, RTIOPORT uPort, RTIOPORT cPorts, uint32_t fAccess,
1060	uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1061	VMMR3DECL(int) DBGFR3BpSetPortIoEx(PUVM pUVM, DBGFBPOWNER hOwner, void *pvUser,
1062	RTIOPORT uPort, RTIOPORT cPorts, uint32_t fAccess,
1063	uint32_t fFlags, uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1064	VMMR3DECL(int) DBGFR3BpSetMmio(PUVM pUVM, RTGCPHYS GCPhys, uint32_t cb, uint32_t fAccess,
1065	uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1066	VMMR3DECL(int) DBGFR3BpSetMmioEx(PUVM pUVM, DBGFBPOWNER hOwner, void *pvUser,
1067	RTGCPHYS GCPhys, uint32_t cb, uint32_t fAccess,
1068	uint32_t fFlags, uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1069	VMMR3DECL(int) DBGFR3BpClear(PUVM pUVM, DBGFBP hBp);
1070	VMMR3DECL(int) DBGFR3BpEnable(PUVM pUVM, DBGFBP hBp);
1071	VMMR3DECL(int) DBGFR3BpDisable(PUVM pUVM, DBGFBP hBp);
1072
1073	/**
1074	* Breakpoint enumeration callback function.
1075	*
1076	* @returns VBox status code.
1077	* The enumeration stops on failure status and VINF_CALLBACK_RETURN.
1078	* @param pUVM The user mode VM handle.
1079	* @param pvUser The user argument.
1080	* @param hBp The breakpoint handle.
1081	* @param pBpPub Pointer to the public breakpoint information. (readonly)
1082	*/
1083	typedef DECLCALLBACKTYPE(int, FNDBGFBPENUM,(PUVM pUVM, void *pvUser, DBGFBP hBp, PCDBGFBPPUB pBpPub));
1084	/** Pointer to a breakpoint enumeration callback function. */
1085	typedef FNDBGFBPENUM *PFNDBGFBPENUM;
1086
1087	VMMR3DECL(int) DBGFR3BpEnum(PUVM pUVM, PFNDBGFBPENUM pfnCallback, void *pvUser);
1088
1089	VMMR3_INT_DECL(int) DBGFR3BpHit(PVM pVM, PVMCPU pVCpu);
1090	/** @} */
1091	#endif /* !IN_RING3 */
1092
1093
1094	#if defined(IN_RING0) \|\| defined(DOXYGEN_RUNNING)
1095	/** @defgroup grp_dbgf_bp_r0 The DBGF Breakpoint Host Context Ring-0 API
1096	* @{ */
1097	VMMR0_INT_DECL(int) DBGFR0BpOwnerSetUpContext(PGVM pGVM, DBGFBPOWNER hBpOwner, PFNDBGFBPHIT pfnBpHit, PFNDBGFBPIOHIT pfnBpIoHit);
1098	VMMR0_INT_DECL(int) DBGFR0BpOwnerDestroyContext(PGVM pGVM, DBGFBPOWNER hBpOwner);
1099
1100	VMMR0_INT_DECL(int) DBGFR0BpSetUpContext(PGVM pGVM, DBGFBP hBp, void *pvUser);
1101	VMMR0_INT_DECL(int) DBGFR0BpDestroyContext(PGVM pGVM, DBGFBP hBp);
1102	/** @} */
1103	#endif /* IN_RING0 \|\| DOXYGEN_RUNNING */
1104
1105	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR7(PVM pVM);
1106	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR0(PVM pVM);
1107	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR1(PVM pVM);
1108	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR2(PVM pVM);
1109	VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR3(PVM pVM);
1110	VMM_INT_DECL(bool) DBGFBpIsHwArmed(PVM pVM);
1111	VMM_INT_DECL(bool) DBGFBpIsHwIoArmed(PVM pVM);
1112	VMM_INT_DECL(bool) DBGFBpIsInt3Armed(PVM pVM);
1113	VMM_INT_DECL(bool) DBGFIsStepping(PVMCPU pVCpu);
1114	VMM_INT_DECL(VBOXSTRICTRC) DBGFBpCheckIo(PVM pVM, PVMCPU pVCpu, PCPUMCTX pCtx, RTIOPORT uIoPort, uint8_t cbValue);
1115	VMM_INT_DECL(VBOXSTRICTRC) DBGFBpCheckPortIo(PVMCC pVM, PVMCPU pVCpu, RTIOPORT uIoPort,
1116	uint32_t fAccess, uint32_t uValue, bool fBefore);
1117	VMM_INT_DECL(VBOXSTRICTRC) DBGFEventGenericWithArgs(PVM pVM, PVMCPU pVCpu, DBGFEVENTTYPE enmEvent, DBGFEVENTCTX enmCtx,
1118	unsigned cArgs, ...);
1119	VMM_INT_DECL(int) DBGFTrap01Handler(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame, RTGCUINTREG uDr6, bool fAltStepping);
1120	VMM_INT_DECL(VBOXSTRICTRC) DBGFTrap03Handler(PVMCC pVM, PVMCPUCC pVCpu, PCPUMCTXCORE pRegFrame);
1121
1122
1123	#ifdef IN_RING3 /* The CPU mode API only works in ring-3. */
1124	VMMR3DECL(CPUMMODE) DBGFR3CpuGetMode(PUVM pUVM, VMCPUID idCpu);
1125	VMMR3DECL(VMCPUID) DBGFR3CpuGetCount(PUVM pUVM);
1126	VMMR3DECL(bool) DBGFR3CpuIsIn64BitCode(PUVM pUVM, VMCPUID idCpu);
1127	VMMR3DECL(bool) DBGFR3CpuIsInV86Code(PUVM pUVM, VMCPUID idCpu);
1128	VMMR3DECL(const char *) DBGFR3CpuGetState(PUVM pUVM, VMCPUID idCpu);
1129	#endif
1130
1131
1132
1133	#ifdef IN_RING3 /* The info callbacks API only works in ring-3. */
1134
1135	struct RTGETOPTSTATE;
1136	union RTGETOPTUNION;
1137
1138	/**
1139	* Info helper callback structure.
1140	*/
1141	typedef struct DBGFINFOHLP
1142	{
1143	/**
1144	* Print formatted string.
1145	*
1146	* @param pHlp Pointer to this structure.
1147	* @param pszFormat The format string.
1148	* @param ... Arguments.
1149	*/
1150	DECLCALLBACKMEMBER(void, pfnPrintf,(PCDBGFINFOHLP pHlp, const char *pszFormat, ...)) RT_IPRT_FORMAT_ATTR(2, 3);
1151
1152	/**
1153	* Print formatted string.
1154	*
1155	* @param pHlp Pointer to this structure.
1156	* @param pszFormat The format string.
1157	* @param args Argument list.
1158	*/
1159	DECLCALLBACKMEMBER(void, pfnPrintfV,(PCDBGFINFOHLP pHlp, const char *pszFormat, va_list args)) RT_IPRT_FORMAT_ATTR(2, 0);
1160
1161	/**
1162	* Report getopt parsing trouble
1163	*
1164	* @param pHlp Pointer to this structure.
1165	* @param rc The RTGetOpt return value.
1166	* @param pValueUnion The value union.
1167	* @param pState The getopt state.
1168	*/
1169	DECLCALLBACKMEMBER(void, pfnGetOptError,(PCDBGFINFOHLP pHlp, int rc, union RTGETOPTUNION *pValueUnion,
1170	struct RTGETOPTSTATE *pState));
1171	} DBGFINFOHLP;
1172
1173
1174	/**
1175	* Info handler, device version.
1176	*
1177	* @param pDevIns The device instance which registered the info.
1178	* @param pHlp Callback functions for doing output.
1179	* @param pszArgs Argument string. Optional and specific to the handler.
1180	*/
1181	typedef DECLCALLBACKTYPE(void, FNDBGFHANDLERDEV,(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs));
1182	/** Pointer to a FNDBGFHANDLERDEV function. */
1183	typedef FNDBGFHANDLERDEV *PFNDBGFHANDLERDEV;
1184
1185	/**
1186	* Info handler, driver version.
1187	*
1188	* @param pDrvIns The driver instance which registered the info.
1189	* @param pHlp Callback functions for doing output.
1190	* @param pszArgs Argument string. Optional and specific to the handler.
1191	*/
1192	typedef DECLCALLBACKTYPE(void, FNDBGFHANDLERDRV,(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, const char *pszArgs));
1193	/** Pointer to a FNDBGFHANDLERDRV function. */
1194	typedef FNDBGFHANDLERDRV *PFNDBGFHANDLERDRV;
1195
1196	/**
1197	* Info handler, internal version.
1198	*
1199	* @param pVM The cross context VM structure.
1200	* @param pHlp Callback functions for doing output.
1201	* @param pszArgs Argument string. Optional and specific to the handler.
1202	*/
1203	typedef DECLCALLBACKTYPE(void, FNDBGFHANDLERINT,(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs));
1204	/** Pointer to a FNDBGFHANDLERINT function. */
1205	typedef FNDBGFHANDLERINT *PFNDBGFHANDLERINT;
1206
1207	/**
1208	* Info handler, external version.
1209	*
1210	* @param pvUser User argument.
1211	* @param pHlp Callback functions for doing output.
1212	* @param pszArgs Argument string. Optional and specific to the handler.
1213	*/
1214	typedef DECLCALLBACKTYPE(void, FNDBGFHANDLEREXT,(void pvUser, PCDBGFINFOHLP pHlp, const char pszArgs));
1215	/** Pointer to a FNDBGFHANDLEREXT function. */
1216	typedef FNDBGFHANDLEREXT *PFNDBGFHANDLEREXT;
1217
1218	/**
1219	* Info handler, device version with argv.
1220	*
1221	* @param pDevIns The device instance which registered the info.
1222	* @param pHlp Callback functions for doing output.
1223	* @param cArgs Number of arguments.
1224	* @param papszArgs Argument vector.
1225	*/
1226	typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVDEV,(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1227	/** Pointer to a FNDBGFINFOARGVDEV function. */
1228	typedef FNDBGFINFOARGVDEV *PFNDBGFINFOARGVDEV;
1229
1230	/**
1231	* Info handler, USB device version with argv.
1232	*
1233	* @param pUsbIns The USB device instance which registered the info.
1234	* @param pHlp Callback functions for doing output.
1235	* @param cArgs Number of arguments.
1236	* @param papszArgs Argument vector.
1237	*/
1238	typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVUSB,(PPDMUSBINS pUsbIns, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1239	/** Pointer to a FNDBGFINFOARGVUSB function. */
1240	typedef FNDBGFINFOARGVUSB *PFNDBGFINFOARGVUSB;
1241
1242	/**
1243	* Info handler, driver version with argv.
1244	*
1245	* @param pDrvIns The driver instance which registered the info.
1246	* @param pHlp Callback functions for doing output.
1247	* @param cArgs Number of arguments.
1248	* @param papszArgs Argument vector.
1249	*/
1250	typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVDRV,(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1251	/** Pointer to a FNDBGFINFOARGVDRV function. */
1252	typedef FNDBGFINFOARGVDRV *PFNDBGFINFOARGVDRV;
1253
1254	/**
1255	* Info handler, internal version with argv.
1256	*
1257	* @param pVM The cross context VM structure.
1258	* @param pHlp Callback functions for doing output.
1259	* @param cArgs Number of arguments.
1260	* @param papszArgs Argument vector.
1261	*/
1262	typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVINT,(PVM pVM, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1263	/** Pointer to a FNDBGFINFOARGVINT function. */
1264	typedef FNDBGFINFOARGVINT *PFNDBGFINFOARGVINT;
1265
1266	/**
1267	* Info handler, external version with argv.
1268	*
1269	* @param pvUser User argument.
1270	* @param pHlp Callback functions for doing output.
1271	* @param cArgs Number of arguments.
1272	* @param papszArgs Argument vector.
1273	*/
1274	typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVEXT,(void pvUser, PCDBGFINFOHLP pHlp, int cArgs, char *papszArgs));
1275	/** Pointer to a FNDBGFINFOARGVEXT function. */
1276	typedef FNDBGFINFOARGVEXT *PFNDBGFINFOARGVEXT;
1277
1278
1279	/** @name Flags for the info registration functions.
1280	* @{ */
1281	/** The handler must run on the EMT. */
1282	#define DBGFINFO_FLAGS_RUN_ON_EMT RT_BIT(0)
1283	/** Call on all EMTs when a specific isn't specified. */
1284	#define DBGFINFO_FLAGS_ALL_EMTS RT_BIT(1)
1285	/** @} */
1286
1287	VMMR3_INT_DECL(int) DBGFR3InfoRegisterDevice(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler, PPDMDEVINS pDevIns);
1288	VMMR3_INT_DECL(int) DBGFR3InfoRegisterDriver(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERDRV pfnHandler, PPDMDRVINS pDrvIns);
1289	VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternal(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERINT pfnHandler);
1290	VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternalEx(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERINT pfnHandler, uint32_t fFlags);
1291	VMMR3DECL(int) DBGFR3InfoRegisterExternal(PUVM pUVM, const char pszName, const char pszDesc, PFNDBGFHANDLEREXT pfnHandler, void *pvUser);
1292
1293	VMMR3_INT_DECL(int) DBGFR3InfoRegisterDeviceArgv(PVM pVM, const char pszName, const char pszDesc, PFNDBGFINFOARGVDEV pfnHandler, PPDMDEVINS pDevIns);
1294	VMMR3_INT_DECL(int) DBGFR3InfoRegisterDriverArgv(PVM pVM, const char pszName, const char pszDesc, PFNDBGFINFOARGVDRV pfnHandler, PPDMDRVINS pDrvIns);
1295	VMMR3_INT_DECL(int) DBGFR3InfoRegisterUsbArgv(PVM pVM, const char pszName, const char pszDesc, PFNDBGFINFOARGVUSB pfnHandler, PPDMUSBINS pUsbIns);
1296	VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternalArgv(PVM pVM, const char pszName, const char pszDesc, PFNDBGFINFOARGVINT pfnHandler, uint32_t fFlags);
1297	VMMR3DECL(int) DBGFR3InfoRegisterExternalArgv(PUVM pUVM, const char pszName, const char pszDesc, PFNDBGFINFOARGVEXT pfnHandler, void *pvUser);
1298
1299	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName);
1300	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName);
1301	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterUsb(PVM pVM, PPDMUSBINS pDrvIns, const char *pszName);
1302	VMMR3_INT_DECL(int) DBGFR3InfoDeregisterInternal(PVM pVM, const char *pszName);
1303	VMMR3DECL(int) DBGFR3InfoDeregisterExternal(PUVM pUVM, const char *pszName);
1304
1305	VMMR3DECL(int) DBGFR3Info(PUVM pUVM, const char pszName, const char pszArgs, PCDBGFINFOHLP pHlp);
1306	VMMR3DECL(int) DBGFR3InfoEx(PUVM pUVM, VMCPUID idCpu, const char pszName, const char pszArgs, PCDBGFINFOHLP pHlp);
1307	VMMR3DECL(int) DBGFR3InfoLogRel(PUVM pUVM, const char pszName, const char pszArgs);
1308	VMMR3DECL(int) DBGFR3InfoStdErr(PUVM pUVM, const char pszName, const char pszArgs);
1309	VMMR3_INT_DECL(int) DBGFR3InfoMulti(PVM pVM, const char pszIncludePat, const char pszExcludePat,
1310	const char *pszSepFmt, PCDBGFINFOHLP pHlp);
1311
1312	/** @def DBGFR3_INFO_LOG
1313	* Display a piece of info writing to the log if enabled.
1314	*
1315	* This is for execution on EMTs and will only show the items on the calling
1316	* EMT. This is to avoid deadlocking against other CPUs if a rendezvous is
1317	* initiated in parallel to this call. (Besides, nobody really wants or need
1318	* info for the other EMTs when using this macro.)
1319	*
1320	* @param a_pVM The shared VM handle.
1321	* @param a_pVCpu The cross context per CPU structure of the calling EMT.
1322	* @param a_pszName The identifier of the info to display.
1323	* @param a_pszArgs Arguments to the info handler.
1324	*/
1325	#ifdef LOG_ENABLED
1326	# define DBGFR3_INFO_LOG(a_pVM, a_pVCpu, a_pszName, a_pszArgs) \
1327	do { \
1328	if (LogIsEnabled()) \
1329	DBGFR3InfoEx((a_pVM)->pUVM, (a_pVCpu)->idCpu, a_pszName, a_pszArgs, NULL); \
1330	} while (0)
1331	#else
1332	# define DBGFR3_INFO_LOG(a_pVM, a_pVCpu, a_pszName, a_pszArgs) do { } while (0)
1333	#endif
1334
1335	/** @def DBGFR3_INFO_LOG_SAFE
1336	* Display a piece of info (rendezvous safe) writing to the log if enabled.
1337	*
1338	* @param a_pVM The shared VM handle.
1339	* @param a_pszName The identifier of the info to display.
1340	* @param a_pszArgs Arguments to the info handler.
1341	*
1342	* @remarks Use DBGFR3_INFO_LOG where ever possible!
1343	*/
1344	#ifdef LOG_ENABLED
1345	# define DBGFR3_INFO_LOG_SAFE(a_pVM, a_pszName, a_pszArgs) \
1346	do { \
1347	if (LogIsEnabled()) \
1348	DBGFR3Info((a_pVM)->pUVM, a_pszName, a_pszArgs, NULL); \
1349	} while (0)
1350	#else
1351	# define DBGFR3_INFO_LOG_SAFE(a_pVM, a_pszName, a_pszArgs) do { } while (0)
1352	#endif
1353
1354	/**
1355	* Enumeration callback for use with DBGFR3InfoEnum.
1356	*
1357	* @returns VBox status code.
1358	* A status code indicating failure will end the enumeration
1359	* and DBGFR3InfoEnum will return with that status code.
1360	* @param pUVM The user mode VM handle.
1361	* @param pszName Info identifier name.
1362	* @param pszDesc The description.
1363	* @param pvUser User parameter.
1364	*/
1365	typedef DECLCALLBACKTYPE(int, FNDBGFINFOENUM,(PUVM pUVM, const char pszName, const char pszDesc, void *pvUser));
1366	/** Pointer to a FNDBGFINFOENUM function. */
1367	typedef FNDBGFINFOENUM *PFNDBGFINFOENUM;
1368
1369	VMMR3DECL(int) DBGFR3InfoEnum(PUVM pUVM, PFNDBGFINFOENUM pfnCallback, void *pvUser);
1370	VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogHlp(void);
1371	VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogRelHlp(void);
1372	VMMR3DECL(void) DBGFR3InfoGenericGetOptError(PCDBGFINFOHLP pHlp, int rc, union RTGETOPTUNION *pValueUnion,
1373	struct RTGETOPTSTATE *pState);
1374
1375	#endif /* IN_RING3 */
1376
1377
1378	#ifdef IN_RING3 /* The log contrl API only works in ring-3. */
1379	VMMR3DECL(int) DBGFR3LogModifyGroups(PUVM pUVM, const char *pszGroupSettings);
1380	VMMR3DECL(int) DBGFR3LogModifyFlags(PUVM pUVM, const char *pszFlagSettings);
1381	VMMR3DECL(int) DBGFR3LogModifyDestinations(PUVM pUVM, const char *pszDestSettings);
1382	#endif /* IN_RING3 */
1383
1384	#ifdef IN_RING3 /* The debug information management APIs only works in ring-3. */
1385
1386	/** Max length (including '\\0') of a symbol name. */
1387	#define DBGF_SYMBOL_NAME_LENGTH 512
1388
1389	/**
1390	* Debug symbol.
1391	*/
1392	typedef struct DBGFSYMBOL
1393	{
1394	/** Symbol value (address). */
1395	RTGCUINTPTR Value;
1396	/** Symbol size. */
1397	uint32_t cb;
1398	/** Symbol Flags. (reserved). */
1399	uint32_t fFlags;
1400	/** Symbol name. */
1401	char szName[DBGF_SYMBOL_NAME_LENGTH];
1402	} DBGFSYMBOL;
1403	/** Pointer to debug symbol. */
1404	typedef DBGFSYMBOL *PDBGFSYMBOL;
1405	/** Pointer to const debug symbol. */
1406	typedef const DBGFSYMBOL *PCDBGFSYMBOL;
1407
1408	/**
1409	* Debug line number information.
1410	*/
1411	typedef struct DBGFLINE
1412	{
1413	/** Address. */
1414	RTGCUINTPTR Address;
1415	/** Line number. */
1416	uint32_t uLineNo;
1417	/** Filename. */
1418	char szFilename[260];
1419	} DBGFLINE;
1420	/** Pointer to debug line number. */
1421	typedef DBGFLINE *PDBGFLINE;
1422	/** Pointer to const debug line number. */
1423	typedef const DBGFLINE *PCDBGFLINE;
1424
1425	/** @name Address spaces aliases.
1426	* @{ */
1427	/** The guest global address space. */
1428	#define DBGF_AS_GLOBAL ((RTDBGAS)-1)
1429	/** The guest kernel address space.
1430	* This is usually resolves to the same as DBGF_AS_GLOBAL. */
1431	#define DBGF_AS_KERNEL ((RTDBGAS)-2)
1432	/** The physical address space. */
1433	#define DBGF_AS_PHYS ((RTDBGAS)-3)
1434	/** Raw-mode context. */
1435	#define DBGF_AS_RC ((RTDBGAS)-4)
1436	/** Ring-0 context. */
1437	#define DBGF_AS_R0 ((RTDBGAS)-5)
1438	/** Raw-mode context and then global guest context.
1439	* When used for looking up information, it works as if the call was first made
1440	* with DBGF_AS_RC and then on failure with DBGF_AS_GLOBAL. When called for
1441	* making address space changes, it works as if DBGF_AS_RC was used. */
1442	#define DBGF_AS_RC_AND_GC_GLOBAL ((RTDBGAS)-6)
1443
1444	/** The first special one. */
1445	#define DBGF_AS_FIRST DBGF_AS_RC_AND_GC_GLOBAL
1446	/** The last special one. */
1447	#define DBGF_AS_LAST DBGF_AS_GLOBAL
1448	#endif
1449	/** The number of special address space handles. */
1450	#define DBGF_AS_COUNT (6U)
1451	#ifdef IN_RING3
1452	/** Converts an alias handle to an array index. */
1453	#define DBGF_AS_ALIAS_2_INDEX(hAlias) \
1454	( (uintptr_t)(hAlias) - (uintptr_t)DBGF_AS_FIRST )
1455	/** Predicat macro that check if the specified handle is an alias. */
1456	#define DBGF_AS_IS_ALIAS(hAlias) \
1457	( DBGF_AS_ALIAS_2_INDEX(hAlias) < DBGF_AS_COUNT )
1458	/** Predicat macro that check if the specified alias is a fixed one or not. */
1459	#define DBGF_AS_IS_FIXED_ALIAS(hAlias) \
1460	( DBGF_AS_ALIAS_2_INDEX(hAlias) < (uintptr_t)DBGF_AS_PHYS - (uintptr_t)DBGF_AS_FIRST + 1U )
1461
1462	/** @} */
1463
1464	VMMR3DECL(RTDBGCFG) DBGFR3AsGetConfig(PUVM pUVM);
1465
1466	VMMR3DECL(int) DBGFR3AsAdd(PUVM pUVM, RTDBGAS hDbgAs, RTPROCESS ProcId);
1467	VMMR3DECL(int) DBGFR3AsDelete(PUVM pUVM, RTDBGAS hDbgAs);
1468	VMMR3DECL(int) DBGFR3AsSetAlias(PUVM pUVM, RTDBGAS hAlias, RTDBGAS hAliasFor);
1469	VMMR3DECL(RTDBGAS) DBGFR3AsResolve(PUVM pUVM, RTDBGAS hAlias);
1470	VMMR3DECL(RTDBGAS) DBGFR3AsResolveAndRetain(PUVM pUVM, RTDBGAS hAlias);
1471	VMMR3DECL(RTDBGAS) DBGFR3AsQueryByName(PUVM pUVM, const char *pszName);
1472	VMMR3DECL(RTDBGAS) DBGFR3AsQueryByPid(PUVM pUVM, RTPROCESS ProcId);
1473
1474	VMMR3DECL(int) DBGFR3AsLoadImage(PUVM pUVM, RTDBGAS hDbgAs, const char pszFilename, const char pszModName,
1475	RTLDRARCH enmArch, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, uint32_t fFlags);
1476	VMMR3DECL(int) DBGFR3AsLoadMap(PUVM pUVM, RTDBGAS hDbgAs, const char pszFilename, const char pszModName, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, RTGCUINTPTR uSubtrahend, uint32_t fFlags);
1477	VMMR3DECL(int) DBGFR3AsLinkModule(PUVM pUVM, RTDBGAS hDbgAs, RTDBGMOD hMod, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, uint32_t fFlags);
1478	VMMR3DECL(int) DBGFR3AsUnlinkModuleByName(PUVM pUVM, RTDBGAS hDbgAs, const char *pszModName);
1479
1480	VMMR3DECL(int) DBGFR3AsSymbolByAddr(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress, uint32_t fFlags,
1481	PRTGCINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
1482	VMMR3DECL(PRTDBGSYMBOL) DBGFR3AsSymbolByAddrA(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress, uint32_t Flags,
1483	PRTGCINTPTR poffDisp, PRTDBGMOD phMod);
1484	VMMR3DECL(int) DBGFR3AsSymbolByName(PUVM pUVM, RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
1485
1486	VMMR3DECL(int) DBGFR3AsLineByAddr(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress,
1487	PRTGCINTPTR poffDisp, PRTDBGLINE pLine, PRTDBGMOD phMod);
1488	VMMR3DECL(PRTDBGLINE) DBGFR3AsLineByAddrA(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress,
1489	PRTGCINTPTR poffDisp, PRTDBGMOD phMod);
1490
1491	/** @name DBGFMOD_PE_F_XXX - flags for
1492	* @{ */
1493	/** NT 3.1 images were a little different, so make allowances for that. */
1494	#define DBGFMODINMEM_F_PE_NT31 RT_BIT_32(0)
1495	/** No container fallback. */
1496	#define DBGFMODINMEM_F_NO_CONTAINER_FALLBACK RT_BIT_32(1)
1497	/** No in-memory reader fallback. */
1498	#define DBGFMODINMEM_F_NO_READER_FALLBACK RT_BIT_32(2)
1499	/** Valid flags. */
1500	#define DBGFMODINMEM_F_VALID_MASK UINT32_C(0x00000007)
1501	/** @} */
1502	VMMR3DECL(int) DBGFR3ModInMem(PUVM pUVM, PCDBGFADDRESS pImageAddr, uint32_t fFlags, const char *pszName,
1503	const char *pszFilename, RTLDRARCH enmArch, uint32_t cbImage,
1504	PRTDBGMOD phDbgMod, PRTERRINFO pErrInfo);
1505
1506	#endif /* IN_RING3 */
1507
1508	#ifdef IN_RING3 /* The stack API only works in ring-3. */
1509
1510	/** Pointer to stack frame info. */
1511	typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
1512	/** Pointer to const stack frame info. */
1513	typedef struct DBGFSTACKFRAME const *PCDBGFSTACKFRAME;
1514	/**
1515	* Info about a stack frame.
1516	*/
1517	typedef struct DBGFSTACKFRAME
1518	{
1519	/** Frame number. */
1520	uint32_t iFrame;
1521	/** Frame flags (DBGFSTACKFRAME_FLAGS_XXX). */
1522	uint32_t fFlags;
1523	/** The stack address of the frame.
1524	* The off member is [e\|r]sp and the Sel member is ss. */
1525	DBGFADDRESS AddrStack;
1526	/** The program counter (PC) address of the frame.
1527	* The off member is [e\|r]ip and the Sel member is cs. */
1528	DBGFADDRESS AddrPC;
1529	/** Pointer to the symbol nearest the program counter (PC). NULL if not found. */
1530	PRTDBGSYMBOL pSymPC;
1531	/** Pointer to the linenumber nearest the program counter (PC). NULL if not found. */
1532	PRTDBGLINE pLinePC;
1533	/** The frame address.
1534	* The off member is [e\|r]bp and the Sel member is ss. */
1535	DBGFADDRESS AddrFrame;
1536	/** The way this frame returns to the next one. */
1537	RTDBGRETURNTYPE enmReturnType;
1538
1539	/** The way the next frame returns.
1540	* Only valid when DBGFSTACKFRAME_FLAGS_UNWIND_INFO_RET is set. */
1541	RTDBGRETURNTYPE enmReturnFrameReturnType;
1542	/** The return frame address.
1543	* The off member is [e\|r]bp and the Sel member is ss. */
1544	DBGFADDRESS AddrReturnFrame;
1545	/** The return stack address.
1546	* The off member is [e\|r]sp and the Sel member is ss. */
1547	DBGFADDRESS AddrReturnStack;
1548
1549	/** The program counter (PC) address which the frame returns to.
1550	* The off member is [e\|r]ip and the Sel member is cs. */
1551	DBGFADDRESS AddrReturnPC;
1552	/** Pointer to the symbol nearest the return PC. NULL if not found. */
1553	PRTDBGSYMBOL pSymReturnPC;
1554	/** Pointer to the linenumber nearest the return PC. NULL if not found. */
1555	PRTDBGLINE pLineReturnPC;
1556
1557	/** 32-bytes of stack arguments. */
1558	union
1559	{
1560	/** 64-bit view */
1561	uint64_t au64[4];
1562	/** 32-bit view */
1563	uint32_t au32[8];
1564	/** 16-bit view */
1565	uint16_t au16[16];
1566	/** 8-bit view */
1567	uint8_t au8[32];
1568	} Args;
1569
1570	/** Number of registers values we can be sure about.
1571	* @note This is generally zero in the first frame. */
1572	uint32_t cSureRegs;
1573	/** Registers we can be sure about (length given by cSureRegs). */
1574	struct DBGFREGVALEX *paSureRegs;
1575
1576	/** Pointer to the next frame.
1577	* Might not be used in some cases, so consider it internal. */
1578	PCDBGFSTACKFRAME pNextInternal;
1579	/** Pointer to the first frame.
1580	* Might not be used in some cases, so consider it internal. */
1581	PCDBGFSTACKFRAME pFirstInternal;
1582	} DBGFSTACKFRAME;
1583
1584	/** @name DBGFSTACKFRAME_FLAGS_XXX - DBGFSTACKFRAME Flags.
1585	* @{ */
1586	/** This is the last stack frame we can read.
1587	* This flag is not set if the walk stop because of max dept or recursion. */
1588	# define DBGFSTACKFRAME_FLAGS_LAST RT_BIT(1)
1589	/** This is the last record because we detected a loop. */
1590	# define DBGFSTACKFRAME_FLAGS_LOOP RT_BIT(2)
1591	/** This is the last record because we reached the maximum depth. */
1592	# define DBGFSTACKFRAME_FLAGS_MAX_DEPTH RT_BIT(3)
1593	/** 16-bit frame. */
1594	# define DBGFSTACKFRAME_FLAGS_16BIT RT_BIT(4)
1595	/** 32-bit frame. */
1596	# define DBGFSTACKFRAME_FLAGS_32BIT RT_BIT(5)
1597	/** 64-bit frame. */
1598	# define DBGFSTACKFRAME_FLAGS_64BIT RT_BIT(6)
1599	/** Real mode or V86 frame. */
1600	# define DBGFSTACKFRAME_FLAGS_REAL_V86 RT_BIT(7)
1601	/** Is a trap frame (NT term). */
1602	# define DBGFSTACKFRAME_FLAGS_TRAP_FRAME RT_BIT(8)
1603
1604	/** Used Odd/even heuristics for far/near return. */
1605	# define DBGFSTACKFRAME_FLAGS_USED_ODD_EVEN RT_BIT(29)
1606	/** Set if we used unwind info to construct the frame. (Kind of internal.) */
1607	# define DBGFSTACKFRAME_FLAGS_USED_UNWIND_INFO RT_BIT(30)
1608	/** Internal: Unwind info used for the return frame. */
1609	# define DBGFSTACKFRAME_FLAGS_UNWIND_INFO_RET RT_BIT(31)
1610	/** @} */
1611
1612	/** @name DBGFCODETYPE
1613	* @{ */
1614	typedef enum DBGFCODETYPE
1615	{
1616	/** The usual invalid 0 value. */
1617	DBGFCODETYPE_INVALID = 0,
1618	/** Stack walk for guest code. */
1619	DBGFCODETYPE_GUEST,
1620	/** Stack walk for hypervisor code. */
1621	DBGFCODETYPE_HYPER,
1622	/** Stack walk for ring 0 code. */
1623	DBGFCODETYPE_RING0,
1624	/** The usual 32-bit blowup. */
1625	DBGFCODETYPE_32BIT_HACK = 0x7fffffff
1626	} DBGFCODETYPE;
1627	/** @} */
1628
1629	VMMR3DECL(int) DBGFR3StackWalkBegin(PUVM pUVM, VMCPUID idCpu, DBGFCODETYPE enmCodeType,
1630	PCDBGFSTACKFRAME *ppFirstFrame);
1631	VMMR3DECL(int) DBGFR3StackWalkBeginEx(PUVM pUVM, VMCPUID idCpu, DBGFCODETYPE enmCodeType, PCDBGFADDRESS pAddrFrame,
1632	PCDBGFADDRESS pAddrStack,PCDBGFADDRESS pAddrPC,
1633	RTDBGRETURNTYPE enmReturnType, PCDBGFSTACKFRAME *ppFirstFrame);
1634	VMMR3DECL(PCDBGFSTACKFRAME) DBGFR3StackWalkNext(PCDBGFSTACKFRAME pCurrent);
1635	VMMR3DECL(void) DBGFR3StackWalkEnd(PCDBGFSTACKFRAME pFirstFrame);
1636
1637	#endif /* IN_RING3 */
1638
1639
1640	#ifdef IN_RING3 /* The disassembly API only works in ring-3. */
1641
1642	/** @name Flags to pass to DBGFR3DisasInstrEx().
1643	* @{ */
1644	/** Disassemble the current guest instruction, with annotations. */
1645	#define DBGF_DISAS_FLAGS_CURRENT_GUEST RT_BIT(0)
1646	/** No annotations for current context. */
1647	#define DBGF_DISAS_FLAGS_NO_ANNOTATION RT_BIT(2)
1648	/** No symbol lookup. */
1649	#define DBGF_DISAS_FLAGS_NO_SYMBOLS RT_BIT(3)
1650	/** No instruction bytes. */
1651	#define DBGF_DISAS_FLAGS_NO_BYTES RT_BIT(4)
1652	/** No address in the output. */
1653	#define DBGF_DISAS_FLAGS_NO_ADDRESS RT_BIT(5)
1654	/** Disassemble original unpatched bytes (PATM). */
1655	#define DBGF_DISAS_FLAGS_UNPATCHED_BYTES RT_BIT(7)
1656	/** Annotate patched instructions. */
1657	#define DBGF_DISAS_FLAGS_ANNOTATE_PATCHED RT_BIT(8)
1658	/** Disassemble in the default mode of the specific context. */
1659	#define DBGF_DISAS_FLAGS_DEFAULT_MODE UINT32_C(0x00000000)
1660	/** Disassemble in 16-bit mode. */
1661	#define DBGF_DISAS_FLAGS_16BIT_MODE UINT32_C(0x10000000)
1662	/** Disassemble in 16-bit mode with real mode address translation. */
1663	#define DBGF_DISAS_FLAGS_16BIT_REAL_MODE UINT32_C(0x20000000)
1664	/** Disassemble in 32-bit mode. */
1665	#define DBGF_DISAS_FLAGS_32BIT_MODE UINT32_C(0x30000000)
1666	/** Disassemble in 64-bit mode. */
1667	#define DBGF_DISAS_FLAGS_64BIT_MODE UINT32_C(0x40000000)
1668	/** The disassembly mode mask. */
1669	#define DBGF_DISAS_FLAGS_MODE_MASK UINT32_C(0x70000000)
1670	/** Mask containing the valid flags. */
1671	#define DBGF_DISAS_FLAGS_VALID_MASK UINT32_C(0x700001ff)
1672	/** @} */
1673
1674	/** Special flat selector. */
1675	#define DBGF_SEL_FLAT 1
1676
1677	VMMR3DECL(int) DBGFR3DisasInstrEx(PUVM pUVM, VMCPUID idCpu, RTSEL Sel, RTGCPTR GCPtr, uint32_t fFlags,
1678	char pszOutput, uint32_t cbOutput, uint32_t pcbInstr);
1679	VMMR3_INT_DECL(int) DBGFR3DisasInstrCurrent(PVMCPU pVCpu, char *pszOutput, uint32_t cbOutput);
1680	VMMR3DECL(int) DBGFR3DisasInstrCurrentLogInternal(PVMCPU pVCpu, const char *pszPrefix);
1681
1682	/** @def DBGFR3_DISAS_INSTR_CUR_LOG
1683	* Disassembles the current guest context instruction and writes it to the log.
1684	* All registers and data will be displayed. Addresses will be attempted resolved to symbols.
1685	*/
1686	#ifdef LOG_ENABLED
1687	# define DBGFR3_DISAS_INSTR_CUR_LOG(pVCpu, pszPrefix) \
1688	do { \
1689	if (LogIsEnabled()) \
1690	DBGFR3DisasInstrCurrentLogInternal(pVCpu, pszPrefix); \
1691	} while (0)
1692	#else
1693	# define DBGFR3_DISAS_INSTR_CUR_LOG(pVCpu, pszPrefix) do { } while (0)
1694	#endif
1695
1696	VMMR3DECL(int) DBGFR3DisasInstrLogInternal(PVMCPU pVCpu, RTSEL Sel, RTGCPTR GCPtr, const char *pszPrefix);
1697
1698	/** @def DBGFR3_DISAS_INSTR_LOG
1699	* Disassembles the specified guest context instruction and writes it to the log.
1700	* Addresses will be attempted resolved to symbols.
1701	* @thread Any EMT.
1702	*/
1703	# ifdef LOG_ENABLED
1704	# define DBGFR3_DISAS_INSTR_LOG(pVCpu, Sel, GCPtr, pszPrefix) \
1705	do { \
1706	if (LogIsEnabled()) \
1707	DBGFR3DisasInstrLogInternal(pVCpu, Sel, GCPtr, pszPrefix); \
1708	} while (0)
1709	# else
1710	# define DBGFR3_DISAS_INSTR_LOG(pVCpu, Sel, GCPtr, pszPrefix) do { } while (0)
1711	# endif
1712	#endif
1713
1714
1715	#ifdef IN_RING3
1716	VMMR3DECL(int) DBGFR3MemScan(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, RTGCUINTPTR cbRange, RTGCUINTPTR uAlign,
1717	const void *pvNeedle, size_t cbNeedle, PDBGFADDRESS pHitAddress);
1718	VMMR3DECL(int) DBGFR3MemRead(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void *pvBuf, size_t cbRead);
1719	VMMR3DECL(int) DBGFR3MemReadString(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, char *pszBuf, size_t cbBuf);
1720	VMMR3DECL(int) DBGFR3MemWrite(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void const *pvBuf, size_t cbRead);
1721	#endif
1722
1723
1724	/** @name Flags for DBGFR3PagingDumpEx, PGMR3DumpHierarchyHCEx and
1725	* PGMR3DumpHierarchyGCEx
1726	* @{ */
1727	/** The CR3 from the current CPU state. */
1728	#define DBGFPGDMP_FLAGS_CURRENT_CR3 RT_BIT_32(0)
1729	/** The current CPU paging mode (PSE, PAE, LM, EPT, NX). */
1730	#define DBGFPGDMP_FLAGS_CURRENT_MODE RT_BIT_32(1)
1731	/** Whether PSE is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
1732	* Same value as X86_CR4_PSE. */
1733	#define DBGFPGDMP_FLAGS_PSE RT_BIT_32(4) /* */
1734	/** Whether PAE is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
1735	* Same value as X86_CR4_PAE. */
1736	#define DBGFPGDMP_FLAGS_PAE RT_BIT_32(5) /* */
1737	/** Whether LME is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
1738	* Same value as MSR_K6_EFER_LME. */
1739	#define DBGFPGDMP_FLAGS_LME RT_BIT_32(8)
1740	/** Whether nested paging is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE). */
1741	#define DBGFPGDMP_FLAGS_NP RT_BIT_32(9)
1742	/** Whether extended nested page tables are enabled
1743	* (!DBGFPGDMP_FLAGS_CURRENT_STATE). */
1744	#define DBGFPGDMP_FLAGS_EPT RT_BIT_32(10)
1745	/** Whether no-execution is enabled (!DBGFPGDMP_FLAGS_CURRENT_STATE).
1746	* Same value as MSR_K6_EFER_NXE. */
1747	#define DBGFPGDMP_FLAGS_NXE RT_BIT_32(11)
1748	/** Whether to print the CR3. */
1749	#define DBGFPGDMP_FLAGS_PRINT_CR3 RT_BIT_32(27)
1750	/** Whether to print the header. */
1751	#define DBGFPGDMP_FLAGS_HEADER RT_BIT_32(28)
1752	/** Whether to dump additional page information. */
1753	#define DBGFPGDMP_FLAGS_PAGE_INFO RT_BIT_32(29)
1754	/** Dump the shadow tables if set.
1755	* Cannot be used together with DBGFPGDMP_FLAGS_GUEST. */
1756	#define DBGFPGDMP_FLAGS_SHADOW RT_BIT_32(30)
1757	/** Dump the guest tables if set.
1758	* Cannot be used together with DBGFPGDMP_FLAGS_SHADOW. */
1759	#define DBGFPGDMP_FLAGS_GUEST RT_BIT_32(31)
1760	/** Mask of valid bits. */
1761	#define DBGFPGDMP_FLAGS_VALID_MASK UINT32_C(0xf8000f33)
1762	/** The mask of bits controlling the paging mode. */
1763	#define DBGFPGDMP_FLAGS_MODE_MASK UINT32_C(0x00000f32)
1764	/** @} */
1765	VMMDECL(int) DBGFR3PagingDumpEx(PUVM pUVM, VMCPUID idCpu, uint32_t fFlags, uint64_t cr3, uint64_t u64FirstAddr,
1766	uint64_t u64LastAddr, uint32_t cMaxDepth, PCDBGFINFOHLP pHlp);
1767
1768
1769	/** @name DBGFR3SelQueryInfo flags.
1770	* @{ */
1771	/** Get the info from the guest descriptor table.
1772	* @note This is more or less a given now when raw-mode was kicked out. */
1773	#define DBGFSELQI_FLAGS_DT_GUEST UINT32_C(0)
1774	/** If currently executing in in 64-bit mode, blow up data selectors. */
1775	#define DBGFSELQI_FLAGS_DT_ADJ_64BIT_MODE UINT32_C(2)
1776	/** @} */
1777	VMMR3DECL(int) DBGFR3SelQueryInfo(PUVM pUVM, VMCPUID idCpu, RTSEL Sel, uint32_t fFlags, PDBGFSELINFO pSelInfo);
1778
1779
1780	/**
1781	* Register identifiers.
1782	*/
1783	typedef enum DBGFREG
1784	{
1785	/* General purpose registers: */
1786	DBGFREG_AL = 0,
1787	DBGFREG_AX = DBGFREG_AL,
1788	DBGFREG_EAX = DBGFREG_AL,
1789	DBGFREG_RAX = DBGFREG_AL,
1790
1791	DBGFREG_CL,
1792	DBGFREG_CX = DBGFREG_CL,
1793	DBGFREG_ECX = DBGFREG_CL,
1794	DBGFREG_RCX = DBGFREG_CL,
1795
1796	DBGFREG_DL,
1797	DBGFREG_DX = DBGFREG_DL,
1798	DBGFREG_EDX = DBGFREG_DL,
1799	DBGFREG_RDX = DBGFREG_DL,
1800
1801	DBGFREG_BL,
1802	DBGFREG_BX = DBGFREG_BL,
1803	DBGFREG_EBX = DBGFREG_BL,
1804	DBGFREG_RBX = DBGFREG_BL,
1805
1806	DBGFREG_SPL,
1807	DBGFREG_SP = DBGFREG_SPL,
1808	DBGFREG_ESP = DBGFREG_SPL,
1809	DBGFREG_RSP = DBGFREG_SPL,
1810
1811	DBGFREG_BPL,
1812	DBGFREG_BP = DBGFREG_BPL,
1813	DBGFREG_EBP = DBGFREG_BPL,
1814	DBGFREG_RBP = DBGFREG_BPL,
1815
1816	DBGFREG_SIL,
1817	DBGFREG_SI = DBGFREG_SIL,
1818	DBGFREG_ESI = DBGFREG_SIL,
1819	DBGFREG_RSI = DBGFREG_SIL,
1820
1821	DBGFREG_DIL,
1822	DBGFREG_DI = DBGFREG_DIL,
1823	DBGFREG_EDI = DBGFREG_DIL,
1824	DBGFREG_RDI = DBGFREG_DIL,
1825
1826	DBGFREG_R8,
1827	DBGFREG_R8B = DBGFREG_R8,
1828	DBGFREG_R8W = DBGFREG_R8,
1829	DBGFREG_R8D = DBGFREG_R8,
1830
1831	DBGFREG_R9,
1832	DBGFREG_R9B = DBGFREG_R9,
1833	DBGFREG_R9W = DBGFREG_R9,
1834	DBGFREG_R9D = DBGFREG_R9,
1835
1836	DBGFREG_R10,
1837	DBGFREG_R10B = DBGFREG_R10,
1838	DBGFREG_R10W = DBGFREG_R10,
1839	DBGFREG_R10D = DBGFREG_R10,
1840
1841	DBGFREG_R11,
1842	DBGFREG_R11B = DBGFREG_R11,
1843	DBGFREG_R11W = DBGFREG_R11,
1844	DBGFREG_R11D = DBGFREG_R11,
1845
1846	DBGFREG_R12,
1847	DBGFREG_R12B = DBGFREG_R12,
1848	DBGFREG_R12W = DBGFREG_R12,
1849	DBGFREG_R12D = DBGFREG_R12,
1850
1851	DBGFREG_R13,
1852	DBGFREG_R13B = DBGFREG_R13,
1853	DBGFREG_R13W = DBGFREG_R13,
1854	DBGFREG_R13D = DBGFREG_R13,
1855
1856	DBGFREG_R14,
1857	DBGFREG_R14B = DBGFREG_R14,
1858	DBGFREG_R14W = DBGFREG_R14,
1859	DBGFREG_R14D = DBGFREG_R14,
1860
1861	DBGFREG_R15,
1862	DBGFREG_R15B = DBGFREG_R15,
1863	DBGFREG_R15W = DBGFREG_R15,
1864	DBGFREG_R15D = DBGFREG_R15,
1865
1866	/* Segments and other special registers: */
1867	DBGFREG_CS,
1868	DBGFREG_CS_ATTR,
1869	DBGFREG_CS_BASE,
1870	DBGFREG_CS_LIMIT,
1871
1872	DBGFREG_DS,
1873	DBGFREG_DS_ATTR,
1874	DBGFREG_DS_BASE,
1875	DBGFREG_DS_LIMIT,
1876
1877	DBGFREG_ES,
1878	DBGFREG_ES_ATTR,
1879	DBGFREG_ES_BASE,
1880	DBGFREG_ES_LIMIT,
1881
1882	DBGFREG_FS,
1883	DBGFREG_FS_ATTR,
1884	DBGFREG_FS_BASE,
1885	DBGFREG_FS_LIMIT,
1886
1887	DBGFREG_GS,
1888	DBGFREG_GS_ATTR,
1889	DBGFREG_GS_BASE,
1890	DBGFREG_GS_LIMIT,
1891
1892	DBGFREG_SS,
1893	DBGFREG_SS_ATTR,
1894	DBGFREG_SS_BASE,
1895	DBGFREG_SS_LIMIT,
1896
1897	DBGFREG_IP,
1898	DBGFREG_EIP = DBGFREG_IP,
1899	DBGFREG_RIP = DBGFREG_IP,
1900
1901	DBGFREG_FLAGS,
1902	DBGFREG_EFLAGS = DBGFREG_FLAGS,
1903	DBGFREG_RFLAGS = DBGFREG_FLAGS,
1904
1905	/* FPU: */
1906	DBGFREG_FCW,
1907	DBGFREG_FSW,
1908	DBGFREG_FTW,
1909	DBGFREG_FOP,
1910	DBGFREG_FPUIP,
1911	DBGFREG_FPUCS,
1912	DBGFREG_FPUDP,
1913	DBGFREG_FPUDS,
1914	DBGFREG_MXCSR,
1915	DBGFREG_MXCSR_MASK,
1916
1917	DBGFREG_ST0,
1918	DBGFREG_ST1,
1919	DBGFREG_ST2,
1920	DBGFREG_ST3,
1921	DBGFREG_ST4,
1922	DBGFREG_ST5,
1923	DBGFREG_ST6,
1924	DBGFREG_ST7,
1925
1926	DBGFREG_MM0,
1927	DBGFREG_MM1,
1928	DBGFREG_MM2,
1929	DBGFREG_MM3,
1930	DBGFREG_MM4,
1931	DBGFREG_MM5,
1932	DBGFREG_MM6,
1933	DBGFREG_MM7,
1934
1935	/* SSE: */
1936	DBGFREG_XMM0,
1937	DBGFREG_XMM1,
1938	DBGFREG_XMM2,
1939	DBGFREG_XMM3,
1940	DBGFREG_XMM4,
1941	DBGFREG_XMM5,
1942	DBGFREG_XMM6,
1943	DBGFREG_XMM7,
1944	DBGFREG_XMM8,
1945	DBGFREG_XMM9,
1946	DBGFREG_XMM10,
1947	DBGFREG_XMM11,
1948	DBGFREG_XMM12,
1949	DBGFREG_XMM13,
1950	DBGFREG_XMM14,
1951	DBGFREG_XMM15,
1952	/** @todo add XMM aliases. */
1953
1954	/* AVX: */
1955	DBGFREG_YMM0,
1956	DBGFREG_YMM1,
1957	DBGFREG_YMM2,
1958	DBGFREG_YMM3,
1959	DBGFREG_YMM4,
1960	DBGFREG_YMM5,
1961	DBGFREG_YMM6,
1962	DBGFREG_YMM7,
1963	DBGFREG_YMM8,
1964	DBGFREG_YMM9,
1965	DBGFREG_YMM10,
1966	DBGFREG_YMM11,
1967	DBGFREG_YMM12,
1968	DBGFREG_YMM13,
1969	DBGFREG_YMM14,
1970	DBGFREG_YMM15,
1971
1972	/* System registers: */
1973	DBGFREG_GDTR_BASE,
1974	DBGFREG_GDTR_LIMIT,
1975	DBGFREG_IDTR_BASE,
1976	DBGFREG_IDTR_LIMIT,
1977	DBGFREG_LDTR,
1978	DBGFREG_LDTR_ATTR,
1979	DBGFREG_LDTR_BASE,
1980	DBGFREG_LDTR_LIMIT,
1981	DBGFREG_TR,
1982	DBGFREG_TR_ATTR,
1983	DBGFREG_TR_BASE,
1984	DBGFREG_TR_LIMIT,
1985
1986	DBGFREG_CR0,
1987	DBGFREG_CR2,
1988	DBGFREG_CR3,
1989	DBGFREG_CR4,
1990	DBGFREG_CR8,
1991
1992	DBGFREG_DR0,
1993	DBGFREG_DR1,
1994	DBGFREG_DR2,
1995	DBGFREG_DR3,
1996	DBGFREG_DR6,
1997	DBGFREG_DR7,
1998
1999	/* MSRs: */
2000	DBGFREG_MSR_IA32_APICBASE,
2001	DBGFREG_MSR_IA32_CR_PAT,
2002	DBGFREG_MSR_IA32_PERF_STATUS,
2003	DBGFREG_MSR_IA32_SYSENTER_CS,
2004	DBGFREG_MSR_IA32_SYSENTER_EIP,
2005	DBGFREG_MSR_IA32_SYSENTER_ESP,
2006	DBGFREG_MSR_IA32_TSC,
2007	DBGFREG_MSR_K6_EFER,
2008	DBGFREG_MSR_K6_STAR,
2009	DBGFREG_MSR_K8_CSTAR,
2010	DBGFREG_MSR_K8_FS_BASE,
2011	DBGFREG_MSR_K8_GS_BASE,
2012	DBGFREG_MSR_K8_KERNEL_GS_BASE,
2013	DBGFREG_MSR_K8_LSTAR,
2014	DBGFREG_MSR_K8_SF_MASK,
2015	DBGFREG_MSR_K8_TSC_AUX,
2016
2017	/** The number of registers to pass to DBGFR3RegQueryAll. */
2018	DBGFREG_ALL_COUNT,
2019
2020	/* Misc aliases that doesn't need be part of the 'all' query: */
2021	DBGFREG_AH = DBGFREG_ALL_COUNT,
2022	DBGFREG_CH,
2023	DBGFREG_DH,
2024	DBGFREG_BH,
2025	DBGFREG_GDTR,
2026	DBGFREG_IDTR,
2027
2028	/** The end of the registers. */
2029	DBGFREG_END,
2030	/** The usual 32-bit type hack. */
2031	DBGFREG_32BIT_HACK = 0x7fffffff
2032	} DBGFREG;
2033	/** Pointer to a register identifier. */
2034	typedef DBGFREG *PDBGFREG;
2035	/** Pointer to a const register identifier. */
2036	typedef DBGFREG const *PCDBGFREG;
2037
2038	/**
2039	* Register value type.
2040	*/
2041	typedef enum DBGFREGVALTYPE
2042	{
2043	DBGFREGVALTYPE_INVALID = 0,
2044	/** Unsigned 8-bit register value. */
2045	DBGFREGVALTYPE_U8,
2046	/** Unsigned 16-bit register value. */
2047	DBGFREGVALTYPE_U16,
2048	/** Unsigned 32-bit register value. */
2049	DBGFREGVALTYPE_U32,
2050	/** Unsigned 64-bit register value. */
2051	DBGFREGVALTYPE_U64,
2052	/** Unsigned 128-bit register value. */
2053	DBGFREGVALTYPE_U128,
2054	/** Unsigned 256-bit register value. */
2055	DBGFREGVALTYPE_U256,
2056	/** Unsigned 512-bit register value. */
2057	DBGFREGVALTYPE_U512,
2058	/** Long double register value. */
2059	DBGFREGVALTYPE_R80,
2060	/** Descriptor table register value. */
2061	DBGFREGVALTYPE_DTR,
2062	/** End of the valid register value types. */
2063	DBGFREGVALTYPE_END,
2064	/** The usual 32-bit type hack. */
2065	DBGFREGVALTYPE_32BIT_HACK = 0x7fffffff
2066	} DBGFREGVALTYPE;
2067	/** Pointer to a register value type. */
2068	typedef DBGFREGVALTYPE *PDBGFREGVALTYPE;
2069
2070	/**
2071	* A generic register value type.
2072	*/
2073	typedef union DBGFREGVAL
2074	{
2075	uint64_t au64[8]; /*< The 64-bit array view. First because of the initializer. /
2076	uint32_t au32[16]; /*< The 32-bit array view. /
2077	uint16_t au16[32]; /*< The 16-bit array view. /
2078	uint8_t au8[64]; /*< The 8-bit array view. /
2079
2080	uint8_t u8; /*< The 8-bit view. /
2081	uint16_t u16; /*< The 16-bit view. /
2082	uint32_t u32; /*< The 32-bit view. /
2083	uint64_t u64; /*< The 64-bit view. /
2084	RTUINT128U u128; /*< The 128-bit view. /
2085	RTUINT256U u256; /*< The 256-bit view. /
2086	RTUINT512U u512; /*< The 512-bit view. /
2087	RTFLOAT80U r80; /*< The 80-bit floating point view. /
2088	RTFLOAT80U2 r80Ex; /*< The 80-bit floating point view v2. /
2089	/** GDTR or LDTR (DBGFREGVALTYPE_DTR). */
2090	struct
2091	{
2092	/** The table address. */
2093	uint64_t u64Base;
2094	/** The table limit (length minus 1). */
2095	uint32_t u32Limit; /*< @todo Limit should be uint16_t /
2096	} dtr;
2097	} DBGFREGVAL;
2098	/** Pointer to a generic register value type. */
2099	typedef DBGFREGVAL *PDBGFREGVAL;
2100	/** Pointer to a const generic register value type. */
2101	typedef DBGFREGVAL const *PCDBGFREGVAL;
2102
2103	/** Initialize a DBGFREGVAL variable to all zeros. */
2104	#define DBGFREGVAL_INITIALIZE_ZERO { { 0, 0, 0, 0, 0, 0, 0, 0 } }
2105	/** Initialize a DBGFREGVAL variable to all bits set . */
2106	#define DBGFREGVAL_INITIALIZE_FFFF { { UINT64_MAX, UINT64_MAX, UINT64_MAX, UINT64_MAX, UINT64_MAX, UINT64_MAX, UINT64_MAX, UINT64_MAX } }
2107
2108	/**
2109	* Extended register value, including register ID and type.
2110	*
2111	* This is currently only used by the stack walker.
2112	*/
2113	typedef struct DBGFREGVALEX
2114	{
2115	/** The register value. */
2116	DBGFREGVAL Value;
2117	/** The register value type. */
2118	DBGFREGVALTYPE enmType;
2119	/** The register ID, DBGFREG_END if not applicable. */
2120	DBGFREG enmReg;
2121	/** Pointer to read-only register name string if no register ID could be found. */
2122	const char *pszName;
2123	} DBGFREGVALEX;
2124	/** Pointer to an extended register value struct. */
2125	typedef DBGFREGVALEX *PDBGFREGVALEX;
2126	/** Pointer to a const extended register value struct. */
2127	typedef DBGFREGVALEX const *PCDBGFREGVALEX;
2128
2129
2130	VMMDECL(ssize_t) DBGFR3RegFormatValue(char *pszBuf, size_t cbBuf, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType, bool fSpecial);
2131	VMMDECL(ssize_t) DBGFR3RegFormatValueEx(char *pszBuf, size_t cbBuf, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType,
2132	unsigned uBase, signed int cchWidth, signed int cchPrecision, uint32_t fFlags);
2133
2134	/**
2135	* Register sub-field descriptor.
2136	*/
2137	typedef struct DBGFREGSUBFIELD
2138	{
2139	/** The name of the sub-field. NULL is used to terminate the array. */
2140	const char *pszName;
2141	/** The index of the first bit. Ignored if pfnGet is set. */
2142	uint8_t iFirstBit;
2143	/** The number of bits. Mandatory. */
2144	uint8_t cBits;
2145	/** The shift count. Not applied when pfnGet is set, but used to
2146	* calculate the minimum type. */
2147	int8_t cShift;
2148	/** Sub-field flags, DBGFREGSUBFIELD_FLAGS_XXX. */
2149	uint8_t fFlags;
2150	/** Getter (optional).
2151	* @remarks Does not take the device lock or anything like that.
2152	*/
2153	DECLCALLBACKMEMBER(int, pfnGet,(void pvUser, struct DBGFREGSUBFIELD const pSubField, PRTUINT128U puValue));
2154	/** Setter (optional).
2155	* @remarks Does not take the device lock or anything like that.
2156	*/
2157	DECLCALLBACKMEMBER(int, pfnSet,(void pvUser, struct DBGFREGSUBFIELD const pSubField, RTUINT128U uValue, RTUINT128U fMask));
2158	} DBGFREGSUBFIELD;
2159	/** Pointer to a const register sub-field descriptor. */
2160	typedef DBGFREGSUBFIELD const *PCDBGFREGSUBFIELD;
2161
2162	/** @name DBGFREGSUBFIELD_FLAGS_XXX
2163	* @{ */
2164	/** The sub-field is read-only. */
2165	#define DBGFREGSUBFIELD_FLAGS_READ_ONLY UINT8_C(0x01)
2166	/** @} */
2167
2168	/** Macro for creating a read-write sub-field entry without getters. */
2169	#define DBGFREGSUBFIELD_RW(a_szName, a_iFirstBit, a_cBits, a_cShift) \
2170	{ a_szName, a_iFirstBit, a_cBits, a_cShift, 0 /fFlags/, NULL /pfnGet/, NULL /pfnSet/ }
2171	/** Macro for creating a read-write sub-field entry with getters. */
2172	#define DBGFREGSUBFIELD_RW_SG(a_szName, a_cBits, a_cShift, a_pfnGet, a_pfnSet) \
2173	{ a_szName, 0 /iFirstBit/, a_cBits, a_cShift, 0 /fFlags/, a_pfnGet, a_pfnSet }
2174	/** Macro for creating a read-only sub-field entry without getters. */
2175	#define DBGFREGSUBFIELD_RO(a_szName, a_iFirstBit, a_cBits, a_cShift) \
2176	{ a_szName, a_iFirstBit, a_cBits, a_cShift, DBGFREGSUBFIELD_FLAGS_READ_ONLY, NULL /pfnGet/, NULL /pfnSet/ }
2177	/** Macro for creating a terminator sub-field entry. */
2178	#define DBGFREGSUBFIELD_TERMINATOR() \
2179	{ NULL, 0, 0, 0, 0, NULL, NULL }
2180
2181	/**
2182	* Register alias descriptor.
2183	*/
2184	typedef struct DBGFREGALIAS
2185	{
2186	/** The alias name. NULL is used to terminate the array. */
2187	const char *pszName;
2188	/** Set to a valid type if the alias has a different type. */
2189	DBGFREGVALTYPE enmType;
2190	} DBGFREGALIAS;
2191	/** Pointer to a const register alias descriptor. */
2192	typedef DBGFREGALIAS const *PCDBGFREGALIAS;
2193
2194	/**
2195	* Register descriptor.
2196	*/
2197	typedef struct DBGFREGDESC
2198	{
2199	/** The normal register name. */
2200	const char *pszName;
2201	/** The register identifier if this is a CPU register. */
2202	DBGFREG enmReg;
2203	/** The default register type. */
2204	DBGFREGVALTYPE enmType;
2205	/** Flags, see DBGFREG_FLAGS_XXX. */
2206	uint32_t fFlags;
2207	/** The internal register indicator.
2208	* For CPU registers this is the offset into the CPUMCTX structure,
2209	* thuse the 'off' prefix. */
2210	uint32_t offRegister;
2211	/** Getter.
2212	* @remarks Does not take the device lock or anything like that.
2213	*/
2214	DECLCALLBACKMEMBER(int, pfnGet,(void pvUser, struct DBGFREGDESC const pDesc, PDBGFREGVAL pValue));
2215	/** Setter.
2216	* @remarks Does not take the device lock or anything like that.
2217	*/
2218	DECLCALLBACKMEMBER(int, pfnSet,(void pvUser, struct DBGFREGDESC const pDesc, PCDBGFREGVAL pValue, PCDBGFREGVAL pfMask));
2219	/** Aliases (optional). */
2220	PCDBGFREGALIAS paAliases;
2221	/** Sub fields (optional). */
2222	PCDBGFREGSUBFIELD paSubFields;
2223	} DBGFREGDESC;
2224
2225	/** @name Macros for constructing DBGFREGDESC arrays.
2226	* @{ */
2227	#define DBGFREGDESC_RW(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet) \
2228	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, NULL /paAlises/, NULL /paSubFields/ }
2229	#define DBGFREGDESC_RO(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet) \
2230	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, NULL /paAlises/, NULL /paSubFields/ }
2231	#define DBGFREGDESC_RW_A(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases) \
2232	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, NULL /paSubFields/ }
2233	#define DBGFREGDESC_RO_A(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases) \
2234	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, NULL /paSubFields/ }
2235	#define DBGFREGDESC_RW_S(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paSubFields) \
2236	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, /paAliases/, a_paSubFields }
2237	#define DBGFREGDESC_RO_S(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paSubFields) \
2238	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, /paAliases/, a_paSubFields }
2239	#define DBGFREGDESC_RW_AS(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields) \
2240	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, 0 /fFlags/, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields }
2241	#define DBGFREGDESC_RO_AS(a_szName, a_TypeSuff, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields) \
2242	{ a_szName, DBGFREG_END, DBGFREGVALTYPE_##a_TypeSuff, DBGFREG_FLAGS_READ_ONLY, a_offRegister, a_pfnGet, a_pfnSet, a_paAliases, a_paSubFields }
2243	#define DBGFREGDESC_TERMINATOR() \
2244	{ NULL, DBGFREG_END, DBGFREGVALTYPE_INVALID, 0, 0, NULL, NULL, NULL, NULL }
2245	/** @} */
2246
2247
2248	/** @name DBGFREG_FLAGS_XXX
2249	* @{ */
2250	/** The register is read-only. */
2251	#define DBGFREG_FLAGS_READ_ONLY RT_BIT_32(0)
2252	/** @} */
2253
2254	/**
2255	* Entry in a batch query or set operation.
2256	*/
2257	typedef struct DBGFREGENTRY
2258	{
2259	/** The register identifier. */
2260	DBGFREG enmReg;
2261	/** The size of the value in bytes. */
2262	DBGFREGVALTYPE enmType;
2263	/** The register value. The valid view is indicated by enmType. */
2264	DBGFREGVAL Val;
2265	} DBGFREGENTRY;
2266	/** Pointer to a register entry in a batch operation. */
2267	typedef DBGFREGENTRY *PDBGFREGENTRY;
2268	/** Pointer to a const register entry in a batch operation. */
2269	typedef DBGFREGENTRY const *PCDBGFREGENTRY;
2270
2271	/** Used with DBGFR3Reg* to indicate the hypervisor register set instead of the
2272	* guest. */
2273	#define DBGFREG_HYPER_VMCPUID UINT32_C(0x01000000)
2274
2275	VMMR3DECL(int) DBGFR3RegCpuQueryU8( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint8_t *pu8);
2276	VMMR3DECL(int) DBGFR3RegCpuQueryU16( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint16_t *pu16);
2277	VMMR3DECL(int) DBGFR3RegCpuQueryU32( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint32_t *pu32);
2278	VMMR3DECL(int) DBGFR3RegCpuQueryU64( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t *pu64);
2279	VMMR3DECL(int) DBGFR3RegCpuQueryU128(PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint128_t *pu128);
2280	/VMMR3DECL(int) DBGFR3RegCpuQueryLrd( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, long double plrd);*/
2281	VMMR3DECL(int) DBGFR3RegCpuQueryXdtr(PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t pu64Base, uint16_t pu16Limit);
2282	#if 0
2283	VMMR3DECL(int) DBGFR3RegCpuQueryBatch(PUVM pUVM,VMCPUID idCpu, PDBGFREGENTRY paRegs, size_t cRegs);
2284	VMMR3DECL(int) DBGFR3RegCpuQueryAll( PUVM pUVM, VMCPUID idCpu, PDBGFREGENTRY paRegs, size_t cRegs);
2285
2286	VMMR3DECL(int) DBGFR3RegCpuSetU8( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint8_t u8);
2287	VMMR3DECL(int) DBGFR3RegCpuSetU16( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint16_t u16);
2288	VMMR3DECL(int) DBGFR3RegCpuSetU32( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint32_t u32);
2289	VMMR3DECL(int) DBGFR3RegCpuSetU64( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t u64);
2290	VMMR3DECL(int) DBGFR3RegCpuSetU128( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint128_t u128);
2291	VMMR3DECL(int) DBGFR3RegCpuSetLrd( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, long double lrd);
2292	VMMR3DECL(int) DBGFR3RegCpuSetBatch( PUVM pUVM, VMCPUID idCpu, PCDBGFREGENTRY paRegs, size_t cRegs);
2293	#endif
2294
2295	VMMR3DECL(const char *) DBGFR3RegCpuName(PUVM pUVM, DBGFREG enmReg, DBGFREGVALTYPE enmType);
2296
2297	VMMR3_INT_DECL(int) DBGFR3RegRegisterCpu(PVM pVM, PVMCPU pVCpu, PCDBGFREGDESC paRegisters, bool fGuestRegs);
2298	VMMR3_INT_DECL(int) DBGFR3RegRegisterDevice(PVM pVM, PCDBGFREGDESC paRegisters, PPDMDEVINS pDevIns,
2299	const char *pszPrefix, uint32_t iInstance);
2300
2301	/**
2302	* Entry in a named batch query or set operation.
2303	*/
2304	typedef struct DBGFREGENTRYNM
2305	{
2306	/** The register name. */
2307	const char *pszName;
2308	/** The size of the value in bytes. */
2309	DBGFREGVALTYPE enmType;
2310	/** The register value. The valid view is indicated by enmType. */
2311	DBGFREGVAL Val;
2312	} DBGFREGENTRYNM;
2313	/** Pointer to a named register entry in a batch operation. */
2314	typedef DBGFREGENTRYNM *PDBGFREGENTRYNM;
2315	/** Pointer to a const named register entry in a batch operation. */
2316	typedef DBGFREGENTRYNM const *PCDBGFREGENTRYNM;
2317
2318	VMMR3DECL(int) DBGFR3RegNmValidate( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg);
2319
2320	VMMR3DECL(int) DBGFR3RegNmQuery( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PDBGFREGVAL pValue, PDBGFREGVALTYPE penmType);
2321	VMMR3DECL(int) DBGFR3RegNmQueryU8( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint8_t pu8);
2322	VMMR3DECL(int) DBGFR3RegNmQueryU16( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint16_t pu16);
2323	VMMR3DECL(int) DBGFR3RegNmQueryU32( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint32_t pu32);
2324	VMMR3DECL(int) DBGFR3RegNmQueryU64( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint64_t pu64);
2325	VMMR3DECL(int) DBGFR3RegNmQueryU128(PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PRTUINT128U pu128);
2326	/VMMR3DECL(int) DBGFR3RegNmQueryLrd( PUVM pUVM, VMCPUID idDefCpu, const char pszReg, long double plrd);/
2327	VMMR3DECL(int) DBGFR3RegNmQueryXdtr(PUVM pUVM, VMCPUID idDefCpu, const char pszReg, uint64_t pu64Base, uint16_t *pu16Limit);
2328	VMMR3DECL(int) DBGFR3RegNmQueryBatch(PUVM pUVM,VMCPUID idDefCpu, PDBGFREGENTRYNM paRegs, size_t cRegs);
2329	VMMR3DECL(int) DBGFR3RegNmQueryAllCount(PUVM pUVM, size_t *pcRegs);
2330	VMMR3DECL(int) DBGFR3RegNmQueryAll( PUVM pUVM, PDBGFREGENTRYNM paRegs, size_t cRegs);
2331
2332	VMMR3DECL(int) DBGFR3RegNmSet( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType);
2333	VMMR3DECL(int) DBGFR3RegNmSetU8( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint8_t u8);
2334	VMMR3DECL(int) DBGFR3RegNmSetU16( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint16_t u16);
2335	VMMR3DECL(int) DBGFR3RegNmSetU32( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint32_t u32);
2336	VMMR3DECL(int) DBGFR3RegNmSetU64( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint64_t u64);
2337	VMMR3DECL(int) DBGFR3RegNmSetU128( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, RTUINT128U u128);
2338	VMMR3DECL(int) DBGFR3RegNmSetLrd( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, long double lrd);
2339	VMMR3DECL(int) DBGFR3RegNmSetBatch( PUVM pUVM, VMCPUID idDefCpu, PCDBGFREGENTRYNM paRegs, size_t cRegs);
2340
2341	/** @todo add enumeration methods. */
2342
2343	VMMR3DECL(int) DBGFR3RegPrintf( PUVM pUVM, VMCPUID idDefCpu, char pszBuf, size_t cbBuf, const char pszFormat, ...);
2344	VMMR3DECL(int) DBGFR3RegPrintfV(PUVM pUVM, VMCPUID idDefCpu, char pszBuf, size_t cbBuf, const char pszFormat, va_list va);
2345
2346
2347	#ifdef IN_RING3
2348
2349	/**
2350	* Guest OS digger interface identifier.
2351	*
2352	* This is for use together with PDBGFR3QueryInterface and is used to
2353	* obtain access to optional interfaces.
2354	*/
2355	typedef enum DBGFOSINTERFACE
2356	{
2357	/** The usual invalid entry. */
2358	DBGFOSINTERFACE_INVALID = 0,
2359	/** Process info. */
2360	DBGFOSINTERFACE_PROCESS,
2361	/** Thread info. */
2362	DBGFOSINTERFACE_THREAD,
2363	/** Kernel message log - DBGFOSIDMESG. */
2364	DBGFOSINTERFACE_DMESG,
2365	/** Windows NT specifics (for the communication with the KD debugger stub). */
2366	DBGFOSINTERFACE_WINNT,
2367	/** The end of the valid entries. */
2368	DBGFOSINTERFACE_END,
2369	/** The usual 32-bit type blowup. */
2370	DBGFOSINTERFACE_32BIT_HACK = 0x7fffffff
2371	} DBGFOSINTERFACE;
2372	/** Pointer to a Guest OS digger interface identifier. */
2373	typedef DBGFOSINTERFACE *PDBGFOSINTERFACE;
2374	/** Pointer to a const Guest OS digger interface identifier. */
2375	typedef DBGFOSINTERFACE const *PCDBGFOSINTERFACE;
2376
2377
2378	/**
2379	* Guest OS Digger Registration Record.
2380	*
2381	* This is used with the DBGFR3OSRegister() API.
2382	*/
2383	typedef struct DBGFOSREG
2384	{
2385	/** Magic value (DBGFOSREG_MAGIC). */
2386	uint32_t u32Magic;
2387	/** Flags. Reserved. */
2388	uint32_t fFlags;
2389	/** The size of the instance data. */
2390	uint32_t cbData;
2391	/** Operative System name. */
2392	char szName[24];
2393
2394	/**
2395	* Constructs the instance.
2396	*
2397	* @returns VBox status code.
2398	* @param pUVM The user mode VM handle.
2399	* @param pVMM The VMM function table.
2400	* @param pvData Pointer to the instance data.
2401	*/
2402	DECLCALLBACKMEMBER(int, pfnConstruct,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData));
2403
2404	/**
2405	* Destroys the instance.
2406	*
2407	* @param pUVM The user mode VM handle.
2408	* @param pVMM The VMM function table.
2409	* @param pvData Pointer to the instance data.
2410	*/
2411	DECLCALLBACKMEMBER(void, pfnDestruct,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData));
2412
2413	/**
2414	* Probes the guest memory for OS finger prints.
2415	*
2416	* No setup or so is performed, it will be followed by a call to pfnInit
2417	* or pfnRefresh that should take care of that.
2418	*
2419	* @returns true if is an OS handled by this module, otherwise false.
2420	* @param pUVM The user mode VM handle.
2421	* @param pVMM The VMM function table.
2422	* @param pvData Pointer to the instance data.
2423	*/
2424	DECLCALLBACKMEMBER(bool, pfnProbe,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData));
2425
2426	/**
2427	* Initializes a fresly detected guest, loading symbols and such useful stuff.
2428	*
2429	* This is called after pfnProbe.
2430	*
2431	* @returns VBox status code.
2432	* @param pUVM The user mode VM handle.
2433	* @param pVMM The VMM function table.
2434	* @param pvData Pointer to the instance data.
2435	*/
2436	DECLCALLBACKMEMBER(int, pfnInit,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData));
2437
2438	/**
2439	* Refreshes symbols and stuff following a redetection of the same OS.
2440	*
2441	* This is called after pfnProbe.
2442	*
2443	* @returns VBox status code.
2444	* @param pUVM The user mode VM handle.
2445	* @param pVMM The VMM function table.
2446	* @param pvData Pointer to the instance data.
2447	*/
2448	DECLCALLBACKMEMBER(int, pfnRefresh,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData));
2449
2450	/**
2451	* Terminates an OS when a new (or none) OS has been detected,
2452	* and before destruction.
2453	*
2454	* This is called after pfnProbe and if needed before pfnDestruct.
2455	*
2456	* @param pUVM The user mode VM handle.
2457	* @param pVMM The VMM function table.
2458	* @param pvData Pointer to the instance data.
2459	*/
2460	DECLCALLBACKMEMBER(void, pfnTerm,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData));
2461
2462	/**
2463	* Queries the version of the running OS.
2464	*
2465	* This is only called after pfnInit().
2466	*
2467	* @returns VBox status code.
2468	* @param pUVM The user mode VM handle.
2469	* @param pVMM The VMM function table.
2470	* @param pvData Pointer to the instance data.
2471	* @param pszVersion Where to store the version string.
2472	* @param cchVersion The size of the version string buffer.
2473	*/
2474	DECLCALLBACKMEMBER(int, pfnQueryVersion,(PUVM pUVM, PCVMMR3VTABLE pVMM, void pvData, char pszVersion, size_t cchVersion));
2475
2476	/**
2477	* Queries the pointer to a interface.
2478	*
2479	* This is called after pfnProbe.
2480	*
2481	* The returned interface must be valid until pfnDestruct is called. Two calls
2482	* to this method with the same @a enmIf value must return the same pointer.
2483	*
2484	* @returns Pointer to the interface if available, NULL if not available.
2485	* @param pUVM The user mode VM handle.
2486	* @param pVMM The VMM function table.
2487	* @param pvData Pointer to the instance data.
2488	* @param enmIf The interface identifier.
2489	*/
2490	DECLCALLBACKMEMBER(void , pfnQueryInterface,(PUVM pUVM, PCVMMR3VTABLE pVMM, void pvData, DBGFOSINTERFACE enmIf));
2491
2492	/**
2493	* Stack unwind assist callback.
2494	*
2495	* This is only called after pfnInit().
2496	*
2497	* @returns VBox status code (allocation error or something of similar fatality).
2498	* @param pUVM The user mode VM handle.
2499	* @param pVMM The VMM function table.
2500	* @param pvData Pointer to the instance data.
2501	* @param idCpu The CPU that's unwinding it's stack.
2502	* @param pFrame The current frame. Okay to modify it a little.
2503	* @param pState The unwind state. Okay to modify it.
2504	* @param pInitialCtx The initial register context.
2505	* @param hAs The address space being used for the unwind.
2506	* @param puScratch Scratch area (initialized to zero, no dtor).
2507	*/
2508	DECLCALLBACKMEMBER(int, pfnStackUnwindAssist,(PUVM pUVM, PCVMMR3VTABLE pVMM, void *pvData, VMCPUID idCpu, PDBGFSTACKFRAME pFrame,
2509	PRTDBGUNWINDSTATE pState, PCCPUMCTX pInitialCtx, RTDBGAS hAs,
2510	uint64_t *puScratch));
2511
2512	/** Trailing magic (DBGFOSREG_MAGIC). */
2513	uint32_t u32EndMagic;
2514	} DBGFOSREG;
2515	/** Pointer to a Guest OS digger registration record. */
2516	typedef DBGFOSREG *PDBGFOSREG;
2517	/** Pointer to a const Guest OS digger registration record. */
2518	typedef DBGFOSREG const *PCDBGFOSREG;
2519
2520	/** Magic value for DBGFOSREG::u32Magic and DBGFOSREG::u32EndMagic. (Hitomi Kanehara) */
2521	#define DBGFOSREG_MAGIC 0x19830808
2522
2523
2524	/**
2525	* Interface for querying kernel log messages (DBGFOSINTERFACE_DMESG).
2526	*/
2527	typedef struct DBGFOSIDMESG
2528	{
2529	/** Trailing magic (DBGFOSIDMESG_MAGIC). */
2530	uint32_t u32Magic;
2531
2532	/**
2533	* Query the kernel log.
2534	*
2535	* @returns VBox status code.
2536	* @retval VERR_NOT_FOUND if the messages could not be located.
2537	* @retval VERR_INVALID_STATE if the messages was found to have unknown/invalid
2538	* format.
2539	* @retval VERR_BUFFER_OVERFLOW if the buffer isn't large enough, pcbActual
2540	* will be set to the required buffer size. The buffer, however, will
2541	* be filled with as much data as it can hold (properly zero terminated
2542	* of course).
2543	*
2544	* @param pThis Pointer to the interface structure.
2545	* @param pUVM The user mode VM handle.
2546	* @param pVMM The VMM function table.
2547	* @param fFlags Flags reserved for future use, MBZ.
2548	* @param cMessages The number of messages to retrieve, counting from the
2549	* end of the log (i.e. like tail), use UINT32_MAX for all.
2550	* @param pszBuf The output buffer.
2551	* @param cbBuf The buffer size.
2552	* @param pcbActual Where to store the number of bytes actually returned,
2553	* including zero terminator. On VERR_BUFFER_OVERFLOW this
2554	* holds the necessary buffer size. Optional.
2555	*/
2556	DECLCALLBACKMEMBER(int, pfnQueryKernelLog,(struct DBGFOSIDMESG *pThis, PUVM pUVM, PCVMMR3VTABLE pVMM, uint32_t fFlags,
2557	uint32_t cMessages, char pszBuf, size_t cbBuf, size_t pcbActual));
2558	/** Trailing magic (DBGFOSIDMESG_MAGIC). */
2559	uint32_t u32EndMagic;
2560	} DBGFOSIDMESG;
2561	/** Pointer to the interface for query kernel log messages (DBGFOSINTERFACE_DMESG). */
2562	typedef DBGFOSIDMESG *PDBGFOSIDMESG;
2563	/** Magic value for DBGFOSIDMESG::32Magic and DBGFOSIDMESG::u32EndMagic. (Kenazburo Oe) */
2564	#define DBGFOSIDMESG_MAGIC UINT32_C(0x19350131)
2565
2566
2567	/**
2568	* Interface for querying Windows NT guest specifics (DBGFOSINTERFACE_WINNT).
2569	*/
2570	typedef struct DBGFOSIWINNT
2571	{
2572	/** Trailing magic (DBGFOSIWINNT_MAGIC). */
2573	uint32_t u32Magic;
2574
2575	/**
2576	* Queries version information.
2577	*
2578	* @returns VBox status code.
2579	* @param pThis Pointer to the interface structure.
2580	* @param pUVM The user mode VM handle.
2581	* @param pVMM The VMM function table.
2582	* @param puVersMajor Where to store the major version part, optional.
2583	* @param puVersMinor Where to store the minor version part, optional.
2584	* @param puBuildNumber Where to store the build number, optional.
2585	* @param pf32Bit Where to store the flag whether this is a 32bit Windows NT, optional.
2586	*/
2587	DECLCALLBACKMEMBER(int, pfnQueryVersion,(struct DBGFOSIWINNT *pThis, PUVM pUVM, PCVMMR3VTABLE pVMM,
2588	uint32_t puVersMajor, uint32_t puVersMinor,
2589	uint32_t puBuildNumber, bool pf32Bit));
2590
2591	/**
2592	* Queries some base kernel pointers.
2593	*
2594	* @returns VBox status code.
2595	* @param pThis Pointer to the interface structure.
2596	* @param pUVM The user mode VM handle.
2597	* @param pVMM The VMM function table.
2598	* @param pGCPtrKernBase Where to store the kernel base on success.
2599	* @param pGCPtrPsLoadedModuleList Where to store the pointer to the laoded module list head on success.
2600	*/
2601	DECLCALLBACKMEMBER(int, pfnQueryKernelPtrs,(struct DBGFOSIWINNT *pThis, PUVM pUVM, PCVMMR3VTABLE pVMM,
2602	PRTGCUINTPTR pGCPtrKernBase, PRTGCUINTPTR pGCPtrPsLoadedModuleList));
2603
2604	/**
2605	* Queries KPCR and KPCRB pointers for the given vCPU.
2606	*
2607	* @returns VBox status code.
2608	* @param pThis Pointer to the interface structure.
2609	* @param pUVM The user mode VM handle.
2610	* @param pVMM The VMM function table.
2611	* @param idCpu The vCPU to query the KPCR/KPCRB for.
2612	* @param pKpcr Where to store the KPCR pointer on success, optional.
2613	* @param pKpcrb Where to store the KPCR pointer on success, optional.
2614	*/
2615	DECLCALLBACKMEMBER(int, pfnQueryKpcrForVCpu,(struct DBGFOSIWINNT *pThis, PUVM pUVM, PCVMMR3VTABLE pVMM, VMCPUID idCpu,
2616	PRTGCUINTPTR pKpcr, PRTGCUINTPTR pKpcrb));
2617
2618	/**
2619	* Queries the current thread for the given vCPU.
2620	*
2621	* @returns VBox status code.
2622	* @param pThis Pointer to the interface structure.
2623	* @param pUVM The user mode VM handle.
2624	* @param pVMM The VMM function table.
2625	* @param idCpu The vCPU to query the KPCR/KPCRB for.
2626	* @param pCurThrd Where to store the CurrentThread pointer on success.
2627	*/
2628	DECLCALLBACKMEMBER(int, pfnQueryCurThrdForVCpu,(struct DBGFOSIWINNT *pThis, PUVM pUVM, PCVMMR3VTABLE pVMM, VMCPUID idCpu,
2629	PRTGCUINTPTR pCurThrd));
2630
2631	/** Trailing magic (DBGFOSIWINNT_MAGIC). */
2632	uint32_t u32EndMagic;
2633	} DBGFOSIWINNT;
2634	/** Pointer to the interface for query kernel log messages (DBGFOSINTERFACE_WINNT). */
2635	typedef DBGFOSIWINNT *PDBGFOSIWINNT;
2636	/** Magic value for DBGFOSIWINNT::32Magic and DBGFOSIWINNT::u32EndMagic. (Dave Cutler) */
2637	#define DBGFOSIWINNT_MAGIC UINT32_C(0x19420313)
2638
2639
2640	VMMR3DECL(int) DBGFR3OSRegister(PUVM pUVM, PCDBGFOSREG pReg);
2641	VMMR3DECL(int) DBGFR3OSDeregister(PUVM pUVM, PCDBGFOSREG pReg);
2642	VMMR3DECL(int) DBGFR3OSDetect(PUVM pUVM, char *pszName, size_t cchName);
2643	VMMR3DECL(int) DBGFR3OSQueryNameAndVersion(PUVM pUVM, char pszName, size_t cchName, char pszVersion, size_t cchVersion);
2644	VMMR3DECL(void *) DBGFR3OSQueryInterface(PUVM pUVM, DBGFOSINTERFACE enmIf);
2645
2646
2647	VMMR3DECL(int) DBGFR3CoreWrite(PUVM pUVM, const char *pszFilename, bool fReplaceFile);
2648
2649
2650
2651	/** @defgroup grp_dbgf_plug_in The DBGF Plug-in Interface
2652	* @{
2653	*/
2654
2655	/** The plug-in module name prefix. */
2656	# define DBGF_PLUG_IN_PREFIX "DbgPlugIn"
2657
2658	/** The name of the plug-in entry point (FNDBGFPLUGIN) */
2659	# define DBGF_PLUG_IN_ENTRYPOINT "DbgPlugInEntry"
2660
2661	/**
2662	* DBGF plug-in operations.
2663	*/
2664	typedef enum DBGFPLUGINOP
2665	{
2666	/** The usual invalid first value. */
2667	DBGFPLUGINOP_INVALID,
2668	/** Initialize the plug-in for a VM, register all the stuff.
2669	* The plug-in will be unloaded on failure.
2670	* uArg: The full VirtualBox version, see VBox/version.h. */
2671	DBGFPLUGINOP_INIT,
2672	/** Terminate the plug-ing for a VM, deregister all the stuff.
2673	* The plug-in will be unloaded after this call regardless of the return
2674	* code. */
2675	DBGFPLUGINOP_TERM,
2676	/** The usual 32-bit hack. */
2677	DBGFPLUGINOP_32BIT_HACK = 0x7fffffff
2678	} DBGFPLUGINOP;
2679
2680	/**
2681	* DBGF plug-in main entry point.
2682	*
2683	* @returns VBox status code.
2684	*
2685	* @param enmOperation The operation.
2686	* @param pUVM The user mode VM handle. This may be NULL.
2687	* @param pVMM The VMM function table.
2688	* @param uArg Extra argument.
2689	*/
2690	typedef DECLCALLBACKTYPE(int, FNDBGFPLUGIN,(DBGFPLUGINOP enmOperation, PUVM pUVM, PCVMMR3VTABLE pVMM, uintptr_t uArg));
2691	/** Pointer to a FNDBGFPLUGIN. */
2692	typedef FNDBGFPLUGIN *PFNDBGFPLUGIN;
2693
2694	/** @copydoc FNDBGFPLUGIN */
2695	DECLEXPORT(int) DbgPlugInEntry(DBGFPLUGINOP enmOperation, PUVM pUVM, PCVMMR3VTABLE pVMM, uintptr_t uArg);
2696
2697	VMMR3DECL(int) DBGFR3PlugInLoad(PUVM pUVM, const char pszPlugIn, char pszActual, size_t cbActual, PRTERRINFO pErrInfo);
2698	VMMR3DECL(int) DBGFR3PlugInUnload(PUVM pUVM, const char *pszName);
2699	VMMR3DECL(void) DBGFR3PlugInLoadAll(PUVM pUVM);
2700	VMMR3DECL(void) DBGFR3PlugInUnloadAll(PUVM pUVM);
2701
2702	/** @} */
2703
2704
2705	/** @defgroup grp_dbgf_types The DBGF type system Interface.
2706	* @{
2707	*/
2708
2709	/** A few forward declarations. */
2710	/** Pointer to a type registration structure. */
2711	typedef struct DBGFTYPEREG *PDBGFTYPEREG;
2712	/** Pointer to a const type registration structure. */
2713	typedef const struct DBGFTYPEREG *PCDBGFTYPEREG;
2714	/** Pointer to a typed buffer. */
2715	typedef struct DBGFTYPEVAL *PDBGFTYPEVAL;
2716
2717	/**
2718	* DBGF built-in types.
2719	*/
2720	typedef enum DBGFTYPEBUILTIN
2721	{
2722	/** The usual invalid first value. */
2723	DBGFTYPEBUILTIN_INVALID,
2724	/** Unsigned 8bit integer. */
2725	DBGFTYPEBUILTIN_UINT8,
2726	/** Signed 8bit integer. */
2727	DBGFTYPEBUILTIN_INT8,
2728	/** Unsigned 16bit integer. */
2729	DBGFTYPEBUILTIN_UINT16,
2730	/** Signed 16bit integer. */
2731	DBGFTYPEBUILTIN_INT16,
2732	/** Unsigned 32bit integer. */
2733	DBGFTYPEBUILTIN_UINT32,
2734	/** Signed 32bit integer. */
2735	DBGFTYPEBUILTIN_INT32,
2736	/** Unsigned 64bit integer. */
2737	DBGFTYPEBUILTIN_UINT64,
2738	/** Signed 64bit integer. */
2739	DBGFTYPEBUILTIN_INT64,
2740	/** 32bit Guest pointer */
2741	DBGFTYPEBUILTIN_PTR32,
2742	/** 64bit Guest pointer */
2743	DBGFTYPEBUILTIN_PTR64,
2744	/** Guest pointer - size depends on the guest bitness */
2745	DBGFTYPEBUILTIN_PTR,
2746	/** Type indicating a size, like size_t this can have different sizes
2747	* on 32bit and 64bit systems */
2748	DBGFTYPEBUILTIN_SIZE,
2749	/** 32bit float. */
2750	DBGFTYPEBUILTIN_FLOAT32,
2751	/** 64bit float (also known as double). */
2752	DBGFTYPEBUILTIN_FLOAT64,
2753	/** Compund types like structs and unions. */
2754	DBGFTYPEBUILTIN_COMPOUND,
2755	/** The usual 32-bit hack. */
2756	DBGFTYPEBUILTIN_32BIT_HACK = 0x7fffffff
2757	} DBGFTYPEBUILTIN;
2758	/** Pointer to a built-in type. */
2759	typedef DBGFTYPEBUILTIN *PDBGFTYPEBUILTIN;
2760	/** Pointer to a const built-in type. */
2761	typedef const DBGFTYPEBUILTIN *PCDBGFTYPEBUILTIN;
2762
2763	/**
2764	* DBGF type value buffer.
2765	*/
2766	typedef union DBGFTYPEVALBUF
2767	{
2768	uint8_t u8;
2769	int8_t i8;
2770	uint16_t u16;
2771	int16_t i16;
2772	uint32_t u32;
2773	int32_t i32;
2774	uint64_t u64;
2775	int64_t i64;
2776	float f32;
2777	double f64;
2778	uint64_t size; /* For the built-in size_t which can be either 32-bit or 64-bit. */
2779	RTGCPTR GCPtr;
2780	/** For embedded structs. */
2781	PDBGFTYPEVAL pVal;
2782	} DBGFTYPEVALBUF;
2783	/** Pointer to a value. */
2784	typedef DBGFTYPEVALBUF *PDBGFTYPEVALBUF;
2785
2786	/**
2787	* DBGF type value entry.
2788	*/
2789	typedef struct DBGFTYPEVALENTRY
2790	{
2791	/** DBGF built-in type. */
2792	DBGFTYPEBUILTIN enmType;
2793	/** Size of the type. */
2794	size_t cbType;
2795	/** Number of entries, for arrays this can be > 1. */
2796	uint32_t cEntries;
2797	/** Value buffer, depends on whether this is an array. */
2798	union
2799	{
2800	/** Single value. */
2801	DBGFTYPEVALBUF Val;
2802	/** Pointer to the array of values. */
2803	PDBGFTYPEVALBUF pVal;
2804	} Buf;
2805	} DBGFTYPEVALENTRY;
2806	/** Pointer to a type value entry. */
2807	typedef DBGFTYPEVALENTRY *PDBGFTYPEVALENTRY;
2808	/** Pointer to a const type value entry. */
2809	typedef const DBGFTYPEVALENTRY *PCDBGFTYPEVALENTRY;
2810
2811	/**
2812	* DBGF typed value.
2813	*/
2814	typedef struct DBGFTYPEVAL
2815	{
2816	/** Pointer to the registration structure for this type. */
2817	PCDBGFTYPEREG pTypeReg;
2818	/** Number of value entries. */
2819	uint32_t cEntries;
2820	/** Variable sized array of value entries. */
2821	DBGFTYPEVALENTRY aEntries[1];
2822	} DBGFTYPEVAL;
2823
2824	/**
2825	* DBGF type variant.
2826	*/
2827	typedef enum DBGFTYPEVARIANT
2828	{
2829	/** The usual invalid first value. */
2830	DBGFTYPEVARIANT_INVALID,
2831	/** A struct. */
2832	DBGFTYPEVARIANT_STRUCT,
2833	/** Union. */
2834	DBGFTYPEVARIANT_UNION,
2835	/** Alias for an existing type. */
2836	DBGFTYPEVARIANT_ALIAS,
2837	/** The usual 32-bit hack. */
2838	DBGFTYPEVARIANT_32BIT_HACK = 0x7fffffff
2839	} DBGFTYPEVARIANT;
2840
2841	/** @name DBGFTYPEREGMEMBER Flags.
2842	* @{ */
2843	/** The member is an array with a fixed size. */
2844	# define DBGFTYPEREGMEMBER_F_ARRAY RT_BIT_32(0)
2845	/** The member denotes a pointer. */
2846	# define DBGFTYPEREGMEMBER_F_POINTER RT_BIT_32(1)
2847	/** @} */
2848
2849	/**
2850	* DBGF type member.
2851	*/
2852	typedef struct DBGFTYPEREGMEMBER
2853	{
2854	/** Name of the member. */
2855	const char *pszName;
2856	/** Flags for this member, see DBGFTYPEREGMEMBER_F_XXX. */
2857	uint32_t fFlags;
2858	/** Type identifier. */
2859	const char *pszType;
2860	/** The number of elements in the array, only valid for arrays. */
2861	uint32_t cElements;
2862	} DBGFTYPEREGMEMBER;
2863	/** Pointer to a member. */
2864	typedef DBGFTYPEREGMEMBER *PDBGFTYPEREGMEMBER;
2865	/** Pointer to a const member. */
2866	typedef const DBGFTYPEREGMEMBER *PCDBGFTYPEREGMEMBER;
2867
2868	/** @name DBGFTYPEREG Flags.
2869	* @{ */
2870	/** The type is a packed structure. */
2871	# define DBGFTYPEREG_F_PACKED RT_BIT_32(0)
2872	/** @} */
2873
2874	/**
2875	* New type registration structure.
2876	*/
2877	typedef struct DBGFTYPEREG
2878	{
2879	/** Name of the type. */
2880	const char *pszType;
2881	/** The type variant. */
2882	DBGFTYPEVARIANT enmVariant;
2883	/** Some registration flags, see DBGFTYPEREG_F_XXX. */
2884	uint32_t fFlags;
2885	/** Number of members this type has, only valid for structs or unions. */
2886	uint32_t cMembers;
2887	/** Pointer to the member fields, only valid for structs or unions. */
2888	PCDBGFTYPEREGMEMBER paMembers;
2889	/** Name of the aliased type for aliases. */
2890	const char *pszAliasedType;
2891	} DBGFTYPEREG;
2892
2893	/**
2894	* DBGF typed value dumper callback.
2895	*
2896	* @returns VBox status code. Any non VINF_SUCCESS status code will abort the dumping.
2897	*
2898	* @param off The byte offset of the entry from the start of the type.
2899	* @param pszField The name of the field for the value.
2900	* @param iLvl The current level.
2901	* @param enmType The type enum.
2902	* @param cbType Size of the type.
2903	* @param pValBuf Pointer to the value buffer.
2904	* @param cValBufs Number of value buffers (for arrays).
2905	* @param pvUser Opaque user data.
2906	*/
2907	typedef DECLCALLBACKTYPE(int, FNDBGFR3TYPEVALDUMP,(uint32_t off, const char *pszField, uint32_t iLvl,
2908	DBGFTYPEBUILTIN enmType, size_t cbType,
2909	PDBGFTYPEVALBUF pValBuf, uint32_t cValBufs, void *pvUser));
2910	/** Pointer to a FNDBGFR3TYPEVALDUMP. */
2911	typedef FNDBGFR3TYPEVALDUMP *PFNDBGFR3TYPEVALDUMP;
2912
2913	/**
2914	* DBGF type information dumper callback.
2915	*
2916	* @returns VBox status code. Any non VINF_SUCCESS status code will abort the dumping.
2917	*
2918	* @param off The byte offset of the entry from the start of the type.
2919	* @param pszField The name of the field for the value.
2920	* @param iLvl The current level.
2921	* @param pszType The type of the field.
2922	* @param fTypeFlags Flags for this type, see DBGFTYPEREGMEMBER_F_XXX.
2923	* @param cElements Number of for the field ( > 0 for arrays).
2924	* @param pvUser Opaque user data.
2925	*/
2926	typedef DECLCALLBACKTYPE(int, FNDBGFR3TYPEDUMP,(uint32_t off, const char *pszField, uint32_t iLvl,
2927	const char *pszType, uint32_t fTypeFlags,
2928	uint32_t cElements, void *pvUser));
2929	/** Pointer to a FNDBGFR3TYPEDUMP. */
2930	typedef FNDBGFR3TYPEDUMP *PFNDBGFR3TYPEDUMP;
2931
2932	VMMR3DECL(int) DBGFR3TypeRegister( PUVM pUVM, uint32_t cTypes, PCDBGFTYPEREG paTypes);
2933	VMMR3DECL(int) DBGFR3TypeDeregister(PUVM pUVM, const char *pszType);
2934	VMMR3DECL(int) DBGFR3TypeQueryReg( PUVM pUVM, const char pszType, PCDBGFTYPEREG ppTypeReg);
2935
2936	VMMR3DECL(int) DBGFR3TypeQuerySize( PUVM pUVM, const char pszType, size_t pcbType);
2937	VMMR3DECL(int) DBGFR3TypeSetSize( PUVM pUVM, const char *pszType, size_t cbType);
2938	VMMR3DECL(int) DBGFR3TypeDumpEx( PUVM pUVM, const char *pszType, uint32_t fFlags,
2939	uint32_t cLvlMax, PFNDBGFR3TYPEDUMP pfnDump, void *pvUser);
2940	VMMR3DECL(int) DBGFR3TypeQueryValByType(PUVM pUVM, PCDBGFADDRESS pAddress, const char *pszType,
2941	PDBGFTYPEVAL *ppVal);
2942	VMMR3DECL(void) DBGFR3TypeValFree(PDBGFTYPEVAL pVal);
2943	VMMR3DECL(int) DBGFR3TypeValDumpEx(PUVM pUVM, PCDBGFADDRESS pAddress, const char *pszType, uint32_t fFlags,
2944	uint32_t cLvlMax, FNDBGFR3TYPEVALDUMP pfnDump, void *pvUser);
2945
2946	/** @} */
2947
2948
2949	/** @defgroup grp_dbgf_flow The DBGF control flow graph Interface.
2950	* @{
2951	*/
2952
2953	/** A DBGF control flow graph handle. */
2954	typedef struct DBGFFLOWINT *DBGFFLOW;
2955	/** Pointer to a DBGF control flow graph handle. */
2956	typedef DBGFFLOW *PDBGFFLOW;
2957	/** A DBGF control flow graph basic block handle. */
2958	typedef struct DBGFFLOWBBINT *DBGFFLOWBB;
2959	/** Pointer to a DBGF control flow graph basic block handle. */
2960	typedef DBGFFLOWBB *PDBGFFLOWBB;
2961	/** A DBGF control flow graph branch table handle. */
2962	typedef struct DBGFFLOWBRANCHTBLINT *DBGFFLOWBRANCHTBL;
2963	/** Pointer to a DBGF flow control graph branch table handle. */
2964	typedef DBGFFLOWBRANCHTBL *PDBGFFLOWBRANCHTBL;
2965	/** A DBGF control flow graph iterator. */
2966	typedef struct DBGFFLOWITINT *DBGFFLOWIT;
2967	/** Pointer to a control flow graph iterator. */
2968	typedef DBGFFLOWIT *PDBGFFLOWIT;
2969	/** A DBGF control flow graph branch table iterator. */
2970	typedef struct DBGFFLOWBRANCHTBLITINT *DBGFFLOWBRANCHTBLIT;
2971	/** Pointer to a control flow graph branch table iterator. */
2972	typedef DBGFFLOWBRANCHTBLIT *PDBGFFLOWBRANCHTBLIT;
2973
2974	/** @name DBGFFLOWBB Flags.
2975	* @{ */
2976	/** The basic block is the entry into the owning control flow graph. */
2977	#define DBGF_FLOW_BB_F_ENTRY RT_BIT_32(0)
2978	/** The basic block was not populated because the limit was reached. */
2979	#define DBGF_FLOW_BB_F_EMPTY RT_BIT_32(1)
2980	/** The basic block is not complete because an error happened during disassembly. */
2981	#define DBGF_FLOW_BB_F_INCOMPLETE_ERR RT_BIT_32(2)
2982	/** The basic block is reached through a branch table. */
2983	#define DBGF_FLOW_BB_F_BRANCH_TABLE RT_BIT_32(3)
2984	/** The basic block consists only of a single call instruction because
2985	* DBGF_FLOW_CREATE_F_CALL_INSN_SEPARATE_BB was given. */
2986	#define DBGF_FLOW_BB_F_CALL_INSN RT_BIT_32(4)
2987	/** The branch target of the call instruction could be deduced and can be queried with
2988	* DBGFR3FlowBbGetBranchAddress(). May only be available when DBGF_FLOW_BB_F_CALL_INSN
2989	* is set. */
2990	#define DBGF_FLOW_BB_F_CALL_INSN_TARGET_KNOWN RT_BIT_32(5)
2991	/** @} */
2992
2993	/** @name Flags controlling the creating of a control flow graph.
2994	* @{ */
2995	/** Default options. */
2996	#define DBGF_FLOW_CREATE_F_DEFAULT 0
2997	/** Tries to resolve indirect branches, useful for code using
2998	* jump tables generated for large switch statements by some compilers. */
2999	#define DBGF_FLOW_CREATE_F_TRY_RESOLVE_INDIRECT_BRANCHES RT_BIT_32(0)
3000	/** Call instructions are placed in a separate basic block. */
3001	#define DBGF_FLOW_CREATE_F_CALL_INSN_SEPARATE_BB RT_BIT_32(1)
3002	/** @} */
3003
3004	/**
3005	* DBGF control graph basic block end type.
3006	*/
3007	typedef enum DBGFFLOWBBENDTYPE
3008	{
3009	/** Invalid type. */
3010	DBGFFLOWBBENDTYPE_INVALID = 0,
3011	/** Basic block is the exit block and has no successor. */
3012	DBGFFLOWBBENDTYPE_EXIT,
3013	/** Basic block is the last disassembled block because the
3014	* maximum amount to disassemble was reached but is not an
3015	* exit block - no successors.
3016	*/
3017	DBGFFLOWBBENDTYPE_LAST_DISASSEMBLED,
3018	/** Unconditional control flow change because the successor is referenced by multiple
3019	* basic blocks. - 1 successor. */
3020	DBGFFLOWBBENDTYPE_UNCOND,
3021	/** Unconditional control flow change because of an direct branch - 1 successor. */
3022	DBGFFLOWBBENDTYPE_UNCOND_JMP,
3023	/** Unconditional control flow change because of an indirect branch - n successors. */
3024	DBGFFLOWBBENDTYPE_UNCOND_INDIRECT_JMP,
3025	/** Conditional control flow change - 2 successors. */
3026	DBGFFLOWBBENDTYPE_COND,
3027	/** 32bit hack. */
3028	DBGFFLOWBBENDTYPE_32BIT_HACK = 0x7fffffff
3029	} DBGFFLOWBBENDTYPE;
3030
3031	/**
3032	* DBGF control flow graph iteration order.
3033	*/
3034	typedef enum DBGFFLOWITORDER
3035	{
3036	/** Invalid order. */
3037	DBGFFLOWITORDER_INVALID = 0,
3038	/** From lowest to highest basic block start address. */
3039	DBGFFLOWITORDER_BY_ADDR_LOWEST_FIRST,
3040	/** From highest to lowest basic block start address. */
3041	DBGFFLOWITORDER_BY_ADDR_HIGHEST_FIRST,
3042	/** Depth first traversing starting from the entry block. */
3043	DBGFFLOWITORDER_DEPTH_FRIST,
3044	/** Breadth first traversing starting from the entry block. */
3045	DBGFFLOWITORDER_BREADTH_FIRST,
3046	/** Usual 32bit hack. */
3047	DBGFFLOWITORDER_32BIT_HACK = 0x7fffffff
3048	} DBGFFLOWITORDER;
3049	/** Pointer to a iteration order enum. */
3050	typedef DBGFFLOWITORDER *PDBGFFLOWITORDER;
3051
3052
3053	VMMR3DECL(int) DBGFR3FlowCreate(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddressStart, uint32_t cbDisasmMax,
3054	uint32_t fFlagsFlow, uint32_t fFlagsDisasm, PDBGFFLOW phFlow);
3055	VMMR3DECL(uint32_t) DBGFR3FlowRetain(DBGFFLOW hFlow);
3056	VMMR3DECL(uint32_t) DBGFR3FlowRelease(DBGFFLOW hFlow);
3057	VMMR3DECL(int) DBGFR3FlowQueryStartBb(DBGFFLOW hFlow, PDBGFFLOWBB phFlowBb);
3058	VMMR3DECL(int) DBGFR3FlowQueryBbByAddress(DBGFFLOW hFlow, PDBGFADDRESS pAddr, PDBGFFLOWBB phFlowBb);
3059	VMMR3DECL(int) DBGFR3FlowQueryBranchTblByAddress(DBGFFLOW hFlow, PDBGFADDRESS pAddr, PDBGFFLOWBRANCHTBL phFlowBranchTbl);
3060	VMMR3DECL(uint32_t) DBGFR3FlowGetBbCount(DBGFFLOW hFlow);
3061	VMMR3DECL(uint32_t) DBGFR3FlowGetBranchTblCount(DBGFFLOW hFlow);
3062	VMMR3DECL(uint32_t) DBGFR3FlowGetCallInsnCount(DBGFFLOW hFlow);
3063
3064	VMMR3DECL(uint32_t) DBGFR3FlowBbRetain(DBGFFLOWBB hFlowBb);
3065	VMMR3DECL(uint32_t) DBGFR3FlowBbRelease(DBGFFLOWBB hFlowBb);
3066	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetStartAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrStart);
3067	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetEndAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrEnd);
3068	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetBranchAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrTarget);
3069	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetFollowingAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrFollow);
3070	VMMR3DECL(DBGFFLOWBBENDTYPE) DBGFR3FlowBbGetType(DBGFFLOWBB hFlowBb);
3071	VMMR3DECL(uint32_t) DBGFR3FlowBbGetInstrCount(DBGFFLOWBB hFlowBb);
3072	VMMR3DECL(uint32_t) DBGFR3FlowBbGetFlags(DBGFFLOWBB hFlowBb);
3073	VMMR3DECL(int) DBGFR3FlowBbQueryBranchTbl(DBGFFLOWBB hFlowBb, PDBGFFLOWBRANCHTBL phBranchTbl);
3074	VMMR3DECL(int) DBGFR3FlowBbQueryError(DBGFFLOWBB hFlowBb, const char **ppszErr);
3075	VMMR3DECL(int) DBGFR3FlowBbQueryInstr(DBGFFLOWBB hFlowBb, uint32_t idxInstr, PDBGFADDRESS pAddrInstr,
3076	uint32_t pcbInstr, const char *ppszInstr);
3077	VMMR3DECL(int) DBGFR3FlowBbQuerySuccessors(DBGFFLOWBB hFlowBb, PDBGFFLOWBB phFlowBbFollow,
3078	PDBGFFLOWBB phFlowBbTarget);
3079	VMMR3DECL(uint32_t) DBGFR3FlowBbGetRefBbCount(DBGFFLOWBB hFlowBb);
3080	VMMR3DECL(int) DBGFR3FlowBbGetRefBb(DBGFFLOWBB hFlowBb, PDBGFFLOWBB pahFlowBbRef, uint32_t cRef);
3081
3082	VMMR3DECL(uint32_t) DBGFR3FlowBranchTblRetain(DBGFFLOWBRANCHTBL hFlowBranchTbl);
3083	VMMR3DECL(uint32_t) DBGFR3FlowBranchTblRelease(DBGFFLOWBRANCHTBL hFlowBranchTbl);
3084	VMMR3DECL(uint32_t) DBGFR3FlowBranchTblGetSlots(DBGFFLOWBRANCHTBL hFlowBranchTbl);
3085	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBranchTblGetStartAddress(DBGFFLOWBRANCHTBL hFlowBranchTbl, PDBGFADDRESS pAddrStart);
3086	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBranchTblGetAddrAtSlot(DBGFFLOWBRANCHTBL hFlowBranchTbl, uint32_t idxSlot, PDBGFADDRESS pAddrSlot);
3087	VMMR3DECL(int) DBGFR3FlowBranchTblQueryAddresses(DBGFFLOWBRANCHTBL hFlowBranchTbl, PDBGFADDRESS paAddrs, uint32_t cAddrs);
3088
3089	VMMR3DECL(int) DBGFR3FlowItCreate(DBGFFLOW hFlow, DBGFFLOWITORDER enmOrder, PDBGFFLOWIT phFlowIt);
3090	VMMR3DECL(void) DBGFR3FlowItDestroy(DBGFFLOWIT hFlowIt);
3091	VMMR3DECL(DBGFFLOWBB) DBGFR3FlowItNext(DBGFFLOWIT hFlowIt);
3092	VMMR3DECL(int) DBGFR3FlowItReset(DBGFFLOWIT hFlowIt);
3093
3094	VMMR3DECL(int) DBGFR3FlowBranchTblItCreate(DBGFFLOW hFlow, DBGFFLOWITORDER enmOrder, PDBGFFLOWBRANCHTBLIT phFlowBranchTblIt);
3095	VMMR3DECL(void) DBGFR3FlowBranchTblItDestroy(DBGFFLOWBRANCHTBLIT hFlowBranchTblIt);
3096	VMMR3DECL(DBGFFLOWBRANCHTBL) DBGFR3FlowBranchTblItNext(DBGFFLOWBRANCHTBLIT hFlowBranchTblIt);
3097	VMMR3DECL(int) DBGFR3FlowBranchTblItReset(DBGFFLOWBRANCHTBLIT hFlowBranchTblIt);
3098
3099	/** @} */
3100
3101
3102	/** @defgroup grp_dbgf_misc Misc DBGF interfaces.
3103	* @{ */
3104	VMMR3DECL(VBOXSTRICTRC) DBGFR3ReportBugCheck(PVM pVM, PVMCPU pVCpu, DBGFEVENTTYPE enmEvent, uint64_t uBugCheck,
3105	uint64_t uP1, uint64_t uP2, uint64_t uP3, uint64_t uP4);
3106	VMMR3DECL(int) DBGFR3FormatBugCheck(PUVM pUVM, char *pszDetails, size_t cbDetails,
3107	uint64_t uP0, uint64_t uP1, uint64_t uP2, uint64_t uP3, uint64_t uP4);
3108	/** @} */
3109	#endif /* IN_RING3 */
3110
3111
3112	/** @defgroup grp_dbgf_tracer DBGF event tracing.
3113	* @{ */
3114	#ifdef IN_RING3
3115	VMMR3_INT_DECL(int) DBGFR3TracerRegisterEvtSrc(PVM pVM, const char *pszName, PDBGFTRACEREVTSRC phEvtSrc);
3116	VMMR3_INT_DECL(int) DBGFR3TracerDeregisterEvtSrc(PVM pVM, DBGFTRACEREVTSRC hEvtSrc);
3117	VMMR3_INT_DECL(int) DBGFR3TracerEvtIoPortCreate(PVM pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTIOPORT cPorts, uint32_t fFlags,
3118	uint32_t iPciRegion);
3119	VMMR3_INT_DECL(int) DBGFR3TracerEvtMmioCreate(PVM pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS cbRegion, uint32_t fFlags,
3120	uint32_t iPciRegion);
3121	#endif
3122
3123	VMM_INT_DECL(int) DBGFTracerEvtMmioMap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS GCPhysMmio);
3124	VMM_INT_DECL(int) DBGFTracerEvtMmioUnmap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion);
3125	VMM_INT_DECL(int) DBGFTracerEvtMmioRead(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS offMmio, const void *pvVal, size_t cbVal);
3126	VMM_INT_DECL(int) DBGFTracerEvtMmioWrite(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS offMmio, const void *pvVal, size_t cbVal);
3127	VMM_INT_DECL(int) DBGFTracerEvtMmioFill(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS offMmio, uint32_t u32Item, uint32_t cbItem, uint32_t cItems);
3128	VMM_INT_DECL(int) DBGFTracerEvtIoPortMap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT IoPortBase);
3129	VMM_INT_DECL(int) DBGFTracerEvtIoPortUnmap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts);
3130	VMM_INT_DECL(int) DBGFTracerEvtIoPortRead(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pvVal, size_t cbVal);
3131	VMM_INT_DECL(int) DBGFTracerEvtIoPortReadStr(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pv, size_t cb,
3132	uint32_t cTransfersReq, uint32_t cTransfersRet);
3133	VMM_INT_DECL(int) DBGFTracerEvtIoPortWrite(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pvVal, size_t cbVal);
3134	VMM_INT_DECL(int) DBGFTracerEvtIoPortWriteStr(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pv, size_t cb,
3135	uint32_t cTransfersReq, uint32_t cTransfersRet);
3136	VMM_INT_DECL(int) DBGFTracerEvtIrq(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, int32_t iIrq, int32_t fIrqLvl);
3137	VMM_INT_DECL(int) DBGFTracerEvtIoApicMsi(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, RTGCPHYS GCPhys, uint32_t u32Val);
3138	VMM_INT_DECL(int) DBGFTracerEvtGCPhysRead(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, RTGCPHYS GCPhys, const void *pvBuf, size_t cbRead);
3139	VMM_INT_DECL(int) DBGFTracerEvtGCPhysWrite(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite);
3140	/** @} */
3141
3142
3143	/** @defgroup grp_dbgf_sample_report DBGF sample report.
3144	* @{ */
3145
3146	/**
3147	* Callback which provides progress information about a currently running
3148	* lengthy operation.
3149	*
3150	* @return VBox status code.
3151	* @retval VERR_DBGF_CANCELLED to cancel the operation.
3152	* @param pvUser The opaque user data associated with this interface.
3153	* @param uPercentage Completion percentage.
3154	*/
3155	typedef DECLCALLBACKTYPE(int, FNDBGFPROGRESS,(void *pvUser, unsigned uPercentage));
3156	/** Pointer to FNDBGFPROGRESS() */
3157	typedef FNDBGFPROGRESS *PFNDBGFPROGRESS;
3158
3159	/** @name Flags to pass to DBGFR3SampleReportCreate().
3160	* @{ */
3161	/** The report creates the call stack in reverse order (bottom to top). */
3162	#define DBGF_SAMPLE_REPORT_F_STACK_REVERSE RT_BIT(0)
3163	/** Mask containing the valid flags. */
3164	#define DBGF_SAMPLE_REPORT_F_VALID_MASK UINT32_C(0x00000001)
3165	/** @} */
3166
3167	VMMR3DECL(int) DBGFR3SampleReportCreate(PUVM pUVM, uint32_t cSampleIntervalMs, uint32_t fFlags, PDBGFSAMPLEREPORT phSample);
3168	VMMR3DECL(uint32_t) DBGFR3SampleReportRetain(DBGFSAMPLEREPORT hSample);
3169	VMMR3DECL(uint32_t) DBGFR3SampleReportRelease(DBGFSAMPLEREPORT hSample);
3170	VMMR3DECL(int) DBGFR3SampleReportStart(DBGFSAMPLEREPORT hSample, uint64_t cSampleUs, PFNDBGFPROGRESS pfnProgress, void *pvUser);
3171	VMMR3DECL(int) DBGFR3SampleReportStop(DBGFSAMPLEREPORT hSample);
3172	VMMR3DECL(int) DBGFR3SampleReportDumpToFile(DBGFSAMPLEREPORT hSample, const char *pszFilename);
3173	/** @} */
3174
3175	/** @} */
3176
3177	RT_C_DECLS_END
3178
3179	#endif /* !VBOX_INCLUDED_vmm_dbgf_h */
3180

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

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

Download in other formats: