VirtualBox

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

Last change on this file since 92070 was 90834, checked in by vboxsync, 3 years ago

Doxygen fixes.

  • Property svn:eol-style set to native
  • Property svn:keywords set to Author Date Id Revision
File size: 133.7 KB
Line 
1/** @file
2 * DBGF - Debugger Facility.
3 */
4
5/*
6 * Copyright (C) 2006-2020 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
40RT_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 */
51VMMR0_INT_DECL(void) DBGFR0InitPerVMData(PGVM pGVM);
52VMMR0_INT_DECL(void) DBGFR0CleanupVM(PGVM pGVM);
53
54/**
55 * Request buffer for DBGFR0TracerCreateReqHandler / VMMR0_DO_DBGF_TRACER_CREATE.
56 * @see DBGFR0TracerCreateReqHandler.
57 */
58typedef 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. */
75typedef DBGFTRACERCREATEREQ *PDBGFTRACERCREATEREQ;
76
77VMMR0_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 */
84typedef 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. */
92typedef DBGFBPINITREQ *PDBGFBPINITREQ;
93
94VMMR0_INT_DECL(int) DBGFR0BpInitReqHandler(PGVM pGVM, PDBGFBPINITREQ pReq);
95VMMR0_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 */
101typedef 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. */
109typedef DBGFBPOWNERINITREQ *PDBGFBPOWNERINITREQ;
110
111VMMR0_INT_DECL(int) DBGFR0BpOwnerInitReqHandler(PGVM pGVM, PDBGFBPOWNERINITREQ pReq);
112
113/**
114 * Request buffer for DBGFR0BpChunkAllocReqHandler / VMMR0_DO_DBGF_CHUNK_ALLOC.
115 * @see DBGFR0BpChunkAllocReqHandler.
116 */
117typedef 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. */
128typedef DBGFBPCHUNKALLOCREQ *PDBGFBPCHUNKALLOCREQ;
129
130VMMR0_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 */
136typedef 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. */
147typedef DBGFBPL2TBLCHUNKALLOCREQ *PDBGFBPL2TBLCHUNKALLOCREQ;
148
149VMMR0_INT_DECL(int) DBGFR0BpL2TblChunkAllocReqHandler(PGVM pGVM, PDBGFBPL2TBLCHUNKALLOCREQ pReq);
150/** @} */
151
152
153#ifdef IN_RING3
154
155/**
156 * Mixed address.
157 */
158typedef 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. */
170typedef DBGFADDRESS *PDBGFADDRESS;
171/** Pointer to a const mixed address. */
172typedef 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
214VMMR3DECL(int) DBGFR3AddrFromSelOff(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, RTSEL Sel, RTUINTPTR off);
215VMMR3DECL(int) DBGFR3AddrFromSelInfoOff(PUVM pUVM, PDBGFADDRESS pAddress, PCDBGFSELINFO pSelInfo, RTUINTPTR off);
216VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromFlat(PUVM pUVM, PDBGFADDRESS pAddress, RTGCUINTPTR FlatPtr);
217VMMR3DECL(PDBGFADDRESS) DBGFR3AddrFromPhys(PUVM pUVM, PDBGFADDRESS pAddress, RTGCPHYS PhysAddr);
218VMMR3_INT_DECL(PDBGFADDRESS) DBGFR3AddrFromHostR0(PDBGFADDRESS pAddress, RTR0UINTPTR R0Ptr);
219VMMR3DECL(bool) DBGFR3AddrIsValid(PUVM pUVM, PCDBGFADDRESS pAddress);
220VMMR3DECL(int) DBGFR3AddrToPhys(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, PRTGCPHYS pGCPhys);
221VMMR3DECL(int) DBGFR3AddrToHostPhys(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, PRTHCPHYS pHCPhys);
222VMMR3DECL(int) DBGFR3AddrToVolatileR3Ptr(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddress, bool fReadOnly, void **ppvR3Ptr);
223VMMR3DECL(PDBGFADDRESS) DBGFR3AddrAdd(PDBGFADDRESS pAddress, RTGCUINTPTR uAddend);
224VMMR3DECL(PDBGFADDRESS) DBGFR3AddrSub(PDBGFADDRESS pAddress, RTGCUINTPTR uSubtrahend);
225
226#endif /* IN_RING3 */
227
228
229
230/**
231 * VMM Debug Event Type.
232 */
233typedef 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;
530AssertCompile(DBGFEVENT_XCPT_LAST - DBGFEVENT_XCPT_FIRST == 0x1f);
531
532/**
533 * The context of an event.
534 */
535typedef 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 */
557typedef 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;
621AssertCompileSizeAlignment(DBGFEVENT, 8);
622AssertCompileSize(DBGFEVENT, 64);
623/** Pointer to VMM Debug Event. */
624typedef DBGFEVENT *PDBGFEVENT;
625/** Pointer to const VMM Debug Event. */
626typedef 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
642VMMR3_INT_DECL(int) DBGFR3Init(PVM pVM);
643VMMR3_INT_DECL(int) DBGFR3Term(PVM pVM);
644VMMR3DECL(void) DBGFR3TermUVM(PUVM pUVM);
645VMMR3_INT_DECL(void) DBGFR3PowerOff(PVM pVM);
646VMMR3_INT_DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta);
647
648VMMR3_INT_DECL(int) DBGFR3VMMForcedAction(PVM pVM, PVMCPU pVCpu);
649VMMR3_INT_DECL(VBOXSTRICTRC) DBGFR3EventHandlePending(PVM pVM, PVMCPU pVCpu);
650VMMR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent);
651VMMR3DECL(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);
653VMMR3DECL(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);
655VMMR3_INT_DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char *pszMsg1, const char *pszMsg2);
656VMMR3_INT_DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent);
657
658VMMR3_INT_DECL(int) DBGFR3PrgStep(PVMCPU pVCpu);
659
660VMMR3DECL(int) DBGFR3Attach(PUVM pUVM);
661VMMR3DECL(int) DBGFR3Detach(PUVM pUVM);
662VMMR3DECL(int) DBGFR3EventWait(PUVM pUVM, RTMSINTERVAL cMillies, PDBGFEVENT pEvent);
663VMMR3DECL(int) DBGFR3Halt(PUVM pUVM, VMCPUID idCpu);
664VMMR3DECL(bool) DBGFR3IsHalted(PUVM pUVM, VMCPUID idCpu);
665VMMR3DECL(int) DBGFR3QueryWaitable(PUVM pUVM);
666VMMR3DECL(int) DBGFR3Resume(PUVM pUVM, VMCPUID idCpu);
667VMMR3DECL(int) DBGFR3InjectNMI(PUVM pUVM, VMCPUID idCpu);
668VMMR3DECL(int) DBGFR3Step(PUVM pUVM, VMCPUID idCpu);
669VMMR3DECL(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 */
705typedef 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. */
715typedef DBGFEVENTCONFIG *PDBGFEVENTCONFIG;
716/** Pointer to a const event config. */
717typedef const DBGFEVENTCONFIG *PCDBGFEVENTCONFIG;
718
719VMMR3DECL(int) DBGFR3EventConfigEx(PUVM pUVM, PCDBGFEVENTCONFIG paConfigs, size_t cConfigs);
720VMMR3DECL(int) DBGFR3EventConfig(PUVM pUVM, DBGFEVENTTYPE enmEvent, bool fEnabled);
721VMMR3DECL(bool) DBGFR3EventIsEnabled(PUVM pUVM, DBGFEVENTTYPE enmEvent);
722VMMR3DECL(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 */
734typedef 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. */
744typedef DBGFINTERRUPTCONFIG *PDBGFINTERRUPTCONFIG;
745/** Pointer to a const interrupt break state config entyr. */
746typedef DBGFINTERRUPTCONFIG const *PCDBGFINTERRUPTCONFIG;
747
748VMMR3DECL(int) DBGFR3InterruptConfigEx(PUVM pUVM, PCDBGFINTERRUPTCONFIG paConfigs, size_t cConfigs);
749VMMR3DECL(int) DBGFR3InterruptHardwareConfig(PUVM pUVM, uint8_t iInterrupt, bool fEnabled);
750VMMR3DECL(int) DBGFR3InterruptSoftwareConfig(PUVM pUVM, uint8_t iInterrupt, bool fEnabled);
751VMMR3DECL(int) DBGFR3InterruptHardwareIsEnabled(PUVM pUVM, uint8_t iInterrupt);
752VMMR3DECL(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. */
815typedef 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 */
876typedef 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;
949AssertCompileSize(DBGFBPPUB, 64 - 8);
950AssertCompileMembersAtSameOffset(DBGFBPPUB, u.GCPtr, DBGFBPPUB, u.Reg.GCPtr);
951AssertCompileMembersAtSameOffset(DBGFBPPUB, u.GCPtr, DBGFBPPUB, u.Int3.GCPtr);
952
953/** Pointer to the visible breakpoint state. */
954typedef DBGFBPPUB *PDBGFBPPUB;
955/** Pointer to a const visible breakpoint state. */
956typedef 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 */
1006typedef DECLCALLBACKTYPE(VBOXSTRICTRC, FNDBGFBPHIT,(PVM pVM, VMCPUID idCpu, void *pvUserBp, DBGFBP hBp, PCDBGFBPPUB pBpPub,
1007 uint16_t fFlags));
1008/** Pointer to a FNDBGFBPHIT(). */
1009typedef 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 */
1034typedef 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(). */
1037typedef FNDBGFBPIOHIT *PFNDBGFBPIOHIT;
1038
1039
1040#ifdef IN_RING3
1041/** @defgroup grp_dbgf_bp_r3 The DBGF Breakpoint Host Context Ring-3 API
1042 * @{ */
1043VMMR3DECL(int) DBGFR3BpOwnerCreate(PUVM pUVM, PFNDBGFBPHIT pfnBpHit, PFNDBGFBPIOHIT pfnBpIoHit, PDBGFBPOWNER phBpOwner);
1044VMMR3DECL(int) DBGFR3BpOwnerDestroy(PUVM pUVM, DBGFBPOWNER hBpOwner);
1045
1046VMMR3DECL(int) DBGFR3BpSetInt3(PUVM pUVM, VMCPUID idSrcCpu, PCDBGFADDRESS pAddress,
1047 uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1048VMMR3DECL(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);
1051VMMR3DECL(int) DBGFR3BpSetReg(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger,
1052 uint64_t iHitDisable, uint8_t fType, uint8_t cb, PDBGFBP phBp);
1053VMMR3DECL(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);
1057VMMR3DECL(int) DBGFR3BpSetREM(PUVM pUVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger,
1058 uint64_t iHitDisable, PDBGFBP phBp);
1059VMMR3DECL(int) DBGFR3BpSetPortIo(PUVM pUVM, RTIOPORT uPort, RTIOPORT cPorts, uint32_t fAccess,
1060 uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1061VMMR3DECL(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);
1064VMMR3DECL(int) DBGFR3BpSetMmio(PUVM pUVM, RTGCPHYS GCPhys, uint32_t cb, uint32_t fAccess,
1065 uint64_t iHitTrigger, uint64_t iHitDisable, PDBGFBP phBp);
1066VMMR3DECL(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);
1069VMMR3DECL(int) DBGFR3BpClear(PUVM pUVM, DBGFBP hBp);
1070VMMR3DECL(int) DBGFR3BpEnable(PUVM pUVM, DBGFBP hBp);
1071VMMR3DECL(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 */
1083typedef DECLCALLBACKTYPE(int, FNDBGFBPENUM,(PUVM pUVM, void *pvUser, DBGFBP hBp, PCDBGFBPPUB pBpPub));
1084/** Pointer to a breakpoint enumeration callback function. */
1085typedef FNDBGFBPENUM *PFNDBGFBPENUM;
1086
1087VMMR3DECL(int) DBGFR3BpEnum(PUVM pUVM, PFNDBGFBPENUM pfnCallback, void *pvUser);
1088
1089VMMR3_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 * @{ */
1097VMMR0_INT_DECL(int) DBGFR0BpOwnerSetUpContext(PGVM pGVM, DBGFBPOWNER hBpOwner, PFNDBGFBPHIT pfnBpHit, PFNDBGFBPIOHIT pfnBpIoHit);
1098VMMR0_INT_DECL(int) DBGFR0BpOwnerDestroyContext(PGVM pGVM, DBGFBPOWNER hBpOwner);
1099
1100VMMR0_INT_DECL(int) DBGFR0BpSetUpContext(PGVM pGVM, DBGFBP hBp, void *pvUser);
1101VMMR0_INT_DECL(int) DBGFR0BpDestroyContext(PGVM pGVM, DBGFBP hBp);
1102/** @} */
1103#endif /* IN_RING0 || DOXYGEN_RUNNING */
1104
1105VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR7(PVM pVM);
1106VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR0(PVM pVM);
1107VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR1(PVM pVM);
1108VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR2(PVM pVM);
1109VMM_INT_DECL(RTGCUINTREG) DBGFBpGetDR3(PVM pVM);
1110VMM_INT_DECL(bool) DBGFBpIsHwArmed(PVM pVM);
1111VMM_INT_DECL(bool) DBGFBpIsHwIoArmed(PVM pVM);
1112VMM_INT_DECL(bool) DBGFBpIsInt3Armed(PVM pVM);
1113VMM_INT_DECL(bool) DBGFIsStepping(PVMCPU pVCpu);
1114VMM_INT_DECL(VBOXSTRICTRC) DBGFBpCheckIo(PVM pVM, PVMCPU pVCpu, PCPUMCTX pCtx, RTIOPORT uIoPort, uint8_t cbValue);
1115VMM_INT_DECL(VBOXSTRICTRC) DBGFBpCheckPortIo(PVMCC pVM, PVMCPU pVCpu, RTIOPORT uIoPort,
1116 uint32_t fAccess, uint32_t uValue, bool fBefore);
1117VMM_INT_DECL(VBOXSTRICTRC) DBGFEventGenericWithArgs(PVM pVM, PVMCPU pVCpu, DBGFEVENTTYPE enmEvent, DBGFEVENTCTX enmCtx,
1118 unsigned cArgs, ...);
1119VMM_INT_DECL(int) DBGFTrap01Handler(PVM pVM, PVMCPU pVCpu, PCPUMCTXCORE pRegFrame, RTGCUINTREG uDr6, bool fAltStepping);
1120VMM_INT_DECL(int) DBGFTrap03Handler(PVMCC pVM, PVMCPUCC pVCpu, PCPUMCTXCORE pRegFrame);
1121
1122
1123#ifdef IN_RING3 /* The CPU mode API only works in ring-3. */
1124VMMR3DECL(CPUMMODE) DBGFR3CpuGetMode(PUVM pUVM, VMCPUID idCpu);
1125VMMR3DECL(VMCPUID) DBGFR3CpuGetCount(PUVM pUVM);
1126VMMR3DECL(bool) DBGFR3CpuIsIn64BitCode(PUVM pUVM, VMCPUID idCpu);
1127VMMR3DECL(bool) DBGFR3CpuIsInV86Code(PUVM pUVM, VMCPUID idCpu);
1128VMMR3DECL(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
1135struct RTGETOPTSTATE;
1136union RTGETOPTUNION;
1137
1138/**
1139 * Info helper callback structure.
1140 */
1141typedef 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 */
1181typedef DECLCALLBACKTYPE(void, FNDBGFHANDLERDEV,(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs));
1182/** Pointer to a FNDBGFHANDLERDEV function. */
1183typedef 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 */
1192typedef DECLCALLBACKTYPE(void, FNDBGFHANDLERDRV,(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, const char *pszArgs));
1193/** Pointer to a FNDBGFHANDLERDRV function. */
1194typedef 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 */
1203typedef DECLCALLBACKTYPE(void, FNDBGFHANDLERINT,(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs));
1204/** Pointer to a FNDBGFHANDLERINT function. */
1205typedef 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 */
1214typedef DECLCALLBACKTYPE(void, FNDBGFHANDLEREXT,(void *pvUser, PCDBGFINFOHLP pHlp, const char *pszArgs));
1215/** Pointer to a FNDBGFHANDLEREXT function. */
1216typedef 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 */
1226typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVDEV,(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1227/** Pointer to a FNDBGFINFOARGVDEV function. */
1228typedef 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 */
1238typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVUSB,(PPDMUSBINS pUsbIns, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1239/** Pointer to a FNDBGFINFOARGVUSB function. */
1240typedef 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 */
1250typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVDRV,(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1251/** Pointer to a FNDBGFINFOARGVDRV function. */
1252typedef 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 */
1262typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVINT,(PVM pVM, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1263/** Pointer to a FNDBGFINFOARGVINT function. */
1264typedef 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 */
1274typedef DECLCALLBACKTYPE(void, FNDBGFINFOARGVEXT,(void *pvUser, PCDBGFINFOHLP pHlp, int cArgs, char **papszArgs));
1275/** Pointer to a FNDBGFINFOARGVEXT function. */
1276typedef 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
1287VMMR3_INT_DECL(int) DBGFR3InfoRegisterDevice(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDEV pfnHandler, PPDMDEVINS pDevIns);
1288VMMR3_INT_DECL(int) DBGFR3InfoRegisterDriver(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERDRV pfnHandler, PPDMDRVINS pDrvIns);
1289VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternal(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERINT pfnHandler);
1290VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternalEx(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLERINT pfnHandler, uint32_t fFlags);
1291VMMR3DECL(int) DBGFR3InfoRegisterExternal(PUVM pUVM, const char *pszName, const char *pszDesc, PFNDBGFHANDLEREXT pfnHandler, void *pvUser);
1292
1293VMMR3_INT_DECL(int) DBGFR3InfoRegisterDeviceArgv(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVDEV pfnHandler, PPDMDEVINS pDevIns);
1294VMMR3_INT_DECL(int) DBGFR3InfoRegisterDriverArgv(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVDRV pfnHandler, PPDMDRVINS pDrvIns);
1295VMMR3_INT_DECL(int) DBGFR3InfoRegisterUsbArgv(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVUSB pfnHandler, PPDMUSBINS pUsbIns);
1296VMMR3_INT_DECL(int) DBGFR3InfoRegisterInternalArgv(PVM pVM, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVINT pfnHandler, uint32_t fFlags);
1297VMMR3DECL(int) DBGFR3InfoRegisterExternalArgv(PUVM pUVM, const char *pszName, const char *pszDesc, PFNDBGFINFOARGVEXT pfnHandler, void *pvUser);
1298
1299VMMR3_INT_DECL(int) DBGFR3InfoDeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName);
1300VMMR3_INT_DECL(int) DBGFR3InfoDeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName);
1301VMMR3_INT_DECL(int) DBGFR3InfoDeregisterUsb(PVM pVM, PPDMUSBINS pDrvIns, const char *pszName);
1302VMMR3_INT_DECL(int) DBGFR3InfoDeregisterInternal(PVM pVM, const char *pszName);
1303VMMR3DECL(int) DBGFR3InfoDeregisterExternal(PUVM pUVM, const char *pszName);
1304
1305VMMR3DECL(int) DBGFR3Info(PUVM pUVM, const char *pszName, const char *pszArgs, PCDBGFINFOHLP pHlp);
1306VMMR3DECL(int) DBGFR3InfoEx(PUVM pUVM, VMCPUID idCpu, const char *pszName, const char *pszArgs, PCDBGFINFOHLP pHlp);
1307VMMR3DECL(int) DBGFR3InfoLogRel(PUVM pUVM, const char *pszName, const char *pszArgs);
1308VMMR3DECL(int) DBGFR3InfoStdErr(PUVM pUVM, const char *pszName, const char *pszArgs);
1309VMMR3_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 */
1365typedef DECLCALLBACKTYPE(int, FNDBGFINFOENUM,(PUVM pUVM, const char *pszName, const char *pszDesc, void *pvUser));
1366/** Pointer to a FNDBGFINFOENUM function. */
1367typedef FNDBGFINFOENUM *PFNDBGFINFOENUM;
1368
1369VMMR3DECL(int) DBGFR3InfoEnum(PUVM pUVM, PFNDBGFINFOENUM pfnCallback, void *pvUser);
1370VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogHlp(void);
1371VMMR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogRelHlp(void);
1372VMMR3DECL(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. */
1379VMMR3DECL(int) DBGFR3LogModifyGroups(PUVM pUVM, const char *pszGroupSettings);
1380VMMR3DECL(int) DBGFR3LogModifyFlags(PUVM pUVM, const char *pszFlagSettings);
1381VMMR3DECL(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 */
1392typedef 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. */
1404typedef DBGFSYMBOL *PDBGFSYMBOL;
1405/** Pointer to const debug symbol. */
1406typedef const DBGFSYMBOL *PCDBGFSYMBOL;
1407
1408/**
1409 * Debug line number information.
1410 */
1411typedef 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. */
1421typedef DBGFLINE *PDBGFLINE;
1422/** Pointer to const debug line number. */
1423typedef 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
1464VMMR3DECL(RTDBGCFG) DBGFR3AsGetConfig(PUVM pUVM);
1465
1466VMMR3DECL(int) DBGFR3AsAdd(PUVM pUVM, RTDBGAS hDbgAs, RTPROCESS ProcId);
1467VMMR3DECL(int) DBGFR3AsDelete(PUVM pUVM, RTDBGAS hDbgAs);
1468VMMR3DECL(int) DBGFR3AsSetAlias(PUVM pUVM, RTDBGAS hAlias, RTDBGAS hAliasFor);
1469VMMR3DECL(RTDBGAS) DBGFR3AsResolve(PUVM pUVM, RTDBGAS hAlias);
1470VMMR3DECL(RTDBGAS) DBGFR3AsResolveAndRetain(PUVM pUVM, RTDBGAS hAlias);
1471VMMR3DECL(RTDBGAS) DBGFR3AsQueryByName(PUVM pUVM, const char *pszName);
1472VMMR3DECL(RTDBGAS) DBGFR3AsQueryByPid(PUVM pUVM, RTPROCESS ProcId);
1473
1474VMMR3DECL(int) DBGFR3AsLoadImage(PUVM pUVM, RTDBGAS hDbgAs, const char *pszFilename, const char *pszModName,
1475 RTLDRARCH enmArch, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, uint32_t fFlags);
1476VMMR3DECL(int) DBGFR3AsLoadMap(PUVM pUVM, RTDBGAS hDbgAs, const char *pszFilename, const char *pszModName, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, RTGCUINTPTR uSubtrahend, uint32_t fFlags);
1477VMMR3DECL(int) DBGFR3AsLinkModule(PUVM pUVM, RTDBGAS hDbgAs, RTDBGMOD hMod, PCDBGFADDRESS pModAddress, RTDBGSEGIDX iModSeg, uint32_t fFlags);
1478VMMR3DECL(int) DBGFR3AsUnlinkModuleByName(PUVM pUVM, RTDBGAS hDbgAs, const char *pszModName);
1479
1480VMMR3DECL(int) DBGFR3AsSymbolByAddr(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress, uint32_t fFlags,
1481 PRTGCINTPTR poffDisp, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
1482VMMR3DECL(PRTDBGSYMBOL) DBGFR3AsSymbolByAddrA(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress, uint32_t Flags,
1483 PRTGCINTPTR poffDisp, PRTDBGMOD phMod);
1484VMMR3DECL(int) DBGFR3AsSymbolByName(PUVM pUVM, RTDBGAS hDbgAs, const char *pszSymbol, PRTDBGSYMBOL pSymbol, PRTDBGMOD phMod);
1485
1486VMMR3DECL(int) DBGFR3AsLineByAddr(PUVM pUVM, RTDBGAS hDbgAs, PCDBGFADDRESS pAddress,
1487 PRTGCINTPTR poffDisp, PRTDBGLINE pLine, PRTDBGMOD phMod);
1488VMMR3DECL(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/** @} */
1502VMMR3DECL(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. */
1511typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
1512/** Pointer to const stack frame info. */
1513typedef struct DBGFSTACKFRAME const *PCDBGFSTACKFRAME;
1514/**
1515 * Info about a stack frame.
1516 */
1517typedef 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 * @{ */
1614typedef 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
1629VMMR3DECL(int) DBGFR3StackWalkBegin(PUVM pUVM, VMCPUID idCpu, DBGFCODETYPE enmCodeType,
1630 PCDBGFSTACKFRAME *ppFirstFrame);
1631VMMR3DECL(int) DBGFR3StackWalkBeginEx(PUVM pUVM, VMCPUID idCpu, DBGFCODETYPE enmCodeType, PCDBGFADDRESS pAddrFrame,
1632 PCDBGFADDRESS pAddrStack,PCDBGFADDRESS pAddrPC,
1633 RTDBGRETURNTYPE enmReturnType, PCDBGFSTACKFRAME *ppFirstFrame);
1634VMMR3DECL(PCDBGFSTACKFRAME) DBGFR3StackWalkNext(PCDBGFSTACKFRAME pCurrent);
1635VMMR3DECL(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
1677VMMR3DECL(int) DBGFR3DisasInstrEx(PUVM pUVM, VMCPUID idCpu, RTSEL Sel, RTGCPTR GCPtr, uint32_t fFlags,
1678 char *pszOutput, uint32_t cbOutput, uint32_t *pcbInstr);
1679VMMR3_INT_DECL(int) DBGFR3DisasInstrCurrent(PVMCPU pVCpu, char *pszOutput, uint32_t cbOutput);
1680VMMR3DECL(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
1696VMMR3DECL(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
1716VMMR3DECL(int) DBGFR3MemScan(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, RTGCUINTPTR cbRange, RTGCUINTPTR uAlign,
1717 const void *pvNeedle, size_t cbNeedle, PDBGFADDRESS pHitAddress);
1718VMMR3DECL(int) DBGFR3MemRead(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, void *pvBuf, size_t cbRead);
1719VMMR3DECL(int) DBGFR3MemReadString(PUVM pUVM, VMCPUID idCpu, PCDBGFADDRESS pAddress, char *pszBuf, size_t cbBuf);
1720VMMR3DECL(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/** @} */
1765VMMDECL(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/** @} */
1777VMMR3DECL(int) DBGFR3SelQueryInfo(PUVM pUVM, VMCPUID idCpu, RTSEL Sel, uint32_t fFlags, PDBGFSELINFO pSelInfo);
1778
1779
1780/**
1781 * Register identifiers.
1782 */
1783typedef 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. */
2034typedef DBGFREG *PDBGFREG;
2035/** Pointer to a const register identifier. */
2036typedef DBGFREG const *PCDBGFREG;
2037
2038/**
2039 * Register value type.
2040 */
2041typedef 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. */
2068typedef DBGFREGVALTYPE *PDBGFREGVALTYPE;
2069
2070/**
2071 * A generic register value type.
2072 */
2073typedef 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. */
2099typedef DBGFREGVAL *PDBGFREGVAL;
2100/** Pointer to a const generic register value type. */
2101typedef 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 */
2113typedef 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. */
2125typedef DBGFREGVALEX *PDBGFREGVALEX;
2126/** Pointer to a const extended register value struct. */
2127typedef DBGFREGVALEX const *PCDBGFREGVALEX;
2128
2129
2130VMMDECL(ssize_t) DBGFR3RegFormatValue(char *pszBuf, size_t cbBuf, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType, bool fSpecial);
2131VMMDECL(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 */
2137typedef 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. */
2160typedef 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 */
2184typedef 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. */
2192typedef DBGFREGALIAS const *PCDBGFREGALIAS;
2193
2194/**
2195 * Register descriptor.
2196 */
2197typedef 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 */
2257typedef 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. */
2267typedef DBGFREGENTRY *PDBGFREGENTRY;
2268/** Pointer to a const register entry in a batch operation. */
2269typedef 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
2275VMMR3DECL(int) DBGFR3RegCpuQueryU8( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint8_t *pu8);
2276VMMR3DECL(int) DBGFR3RegCpuQueryU16( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint16_t *pu16);
2277VMMR3DECL(int) DBGFR3RegCpuQueryU32( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint32_t *pu32);
2278VMMR3DECL(int) DBGFR3RegCpuQueryU64( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t *pu64);
2279VMMR3DECL(int) DBGFR3RegCpuQueryU128(PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint128_t *pu128);
2280VMMR3DECL(int) DBGFR3RegCpuQueryLrd( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, long double *plrd);
2281VMMR3DECL(int) DBGFR3RegCpuQueryXdtr(PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t *pu64Base, uint16_t *pu16Limit);
2282#if 0
2283VMMR3DECL(int) DBGFR3RegCpuQueryBatch(PUVM pUVM,VMCPUID idCpu, PDBGFREGENTRY paRegs, size_t cRegs);
2284VMMR3DECL(int) DBGFR3RegCpuQueryAll( PUVM pUVM, VMCPUID idCpu, PDBGFREGENTRY paRegs, size_t cRegs);
2285
2286VMMR3DECL(int) DBGFR3RegCpuSetU8( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint8_t u8);
2287VMMR3DECL(int) DBGFR3RegCpuSetU16( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint16_t u16);
2288VMMR3DECL(int) DBGFR3RegCpuSetU32( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint32_t u32);
2289VMMR3DECL(int) DBGFR3RegCpuSetU64( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint64_t u64);
2290VMMR3DECL(int) DBGFR3RegCpuSetU128( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, uint128_t u128);
2291VMMR3DECL(int) DBGFR3RegCpuSetLrd( PUVM pUVM, VMCPUID idCpu, DBGFREG enmReg, long double lrd);
2292VMMR3DECL(int) DBGFR3RegCpuSetBatch( PUVM pUVM, VMCPUID idCpu, PCDBGFREGENTRY paRegs, size_t cRegs);
2293#endif
2294
2295VMMR3DECL(const char *) DBGFR3RegCpuName(PUVM pUVM, DBGFREG enmReg, DBGFREGVALTYPE enmType);
2296
2297VMMR3_INT_DECL(int) DBGFR3RegRegisterCpu(PVM pVM, PVMCPU pVCpu, PCDBGFREGDESC paRegisters, bool fGuestRegs);
2298VMMR3_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 */
2304typedef 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. */
2314typedef DBGFREGENTRYNM *PDBGFREGENTRYNM;
2315/** Pointer to a const named register entry in a batch operation. */
2316typedef DBGFREGENTRYNM const *PCDBGFREGENTRYNM;
2317
2318VMMR3DECL(int) DBGFR3RegNmValidate( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg);
2319
2320VMMR3DECL(int) DBGFR3RegNmQuery( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PDBGFREGVAL pValue, PDBGFREGVALTYPE penmType);
2321VMMR3DECL(int) DBGFR3RegNmQueryU8( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint8_t *pu8);
2322VMMR3DECL(int) DBGFR3RegNmQueryU16( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint16_t *pu16);
2323VMMR3DECL(int) DBGFR3RegNmQueryU32( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint32_t *pu32);
2324VMMR3DECL(int) DBGFR3RegNmQueryU64( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint64_t *pu64);
2325VMMR3DECL(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);*/
2327VMMR3DECL(int) DBGFR3RegNmQueryXdtr(PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint64_t *pu64Base, uint16_t *pu16Limit);
2328VMMR3DECL(int) DBGFR3RegNmQueryBatch(PUVM pUVM,VMCPUID idDefCpu, PDBGFREGENTRYNM paRegs, size_t cRegs);
2329VMMR3DECL(int) DBGFR3RegNmQueryAllCount(PUVM pUVM, size_t *pcRegs);
2330VMMR3DECL(int) DBGFR3RegNmQueryAll( PUVM pUVM, PDBGFREGENTRYNM paRegs, size_t cRegs);
2331
2332VMMR3DECL(int) DBGFR3RegNmSet( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, PCDBGFREGVAL pValue, DBGFREGVALTYPE enmType);
2333VMMR3DECL(int) DBGFR3RegNmSetU8( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint8_t u8);
2334VMMR3DECL(int) DBGFR3RegNmSetU16( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint16_t u16);
2335VMMR3DECL(int) DBGFR3RegNmSetU32( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint32_t u32);
2336VMMR3DECL(int) DBGFR3RegNmSetU64( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, uint64_t u64);
2337VMMR3DECL(int) DBGFR3RegNmSetU128( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, RTUINT128U u128);
2338VMMR3DECL(int) DBGFR3RegNmSetLrd( PUVM pUVM, VMCPUID idDefCpu, const char *pszReg, long double lrd);
2339VMMR3DECL(int) DBGFR3RegNmSetBatch( PUVM pUVM, VMCPUID idDefCpu, PCDBGFREGENTRYNM paRegs, size_t cRegs);
2340
2341/** @todo add enumeration methods. */
2342
2343VMMR3DECL(int) DBGFR3RegPrintf( PUVM pUVM, VMCPUID idDefCpu, char *pszBuf, size_t cbBuf, const char *pszFormat, ...);
2344VMMR3DECL(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 */
2355typedef 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. */
2373typedef DBGFOSINTERFACE *PDBGFOSINTERFACE;
2374/** Pointer to a const Guest OS digger interface identifier. */
2375typedef DBGFOSINTERFACE const *PCDBGFOSINTERFACE;
2376
2377
2378/**
2379 * Guest OS Digger Registration Record.
2380 *
2381 * This is used with the DBGFR3OSRegister() API.
2382 */
2383typedef 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 pvData Pointer to the instance data.
2400 */
2401 DECLCALLBACKMEMBER(int, pfnConstruct,(PUVM pUVM, void *pvData));
2402
2403 /**
2404 * Destroys the instance.
2405 *
2406 * @param pUVM The user mode VM handle.
2407 * @param pvData Pointer to the instance data.
2408 */
2409 DECLCALLBACKMEMBER(void, pfnDestruct,(PUVM pUVM, void *pvData));
2410
2411 /**
2412 * Probes the guest memory for OS finger prints.
2413 *
2414 * No setup or so is performed, it will be followed by a call to pfnInit
2415 * or pfnRefresh that should take care of that.
2416 *
2417 * @returns true if is an OS handled by this module, otherwise false.
2418 * @param pUVM The user mode VM handle.
2419 * @param pvData Pointer to the instance data.
2420 */
2421 DECLCALLBACKMEMBER(bool, pfnProbe,(PUVM pUVM, void *pvData));
2422
2423 /**
2424 * Initializes a fresly detected guest, loading symbols and such useful stuff.
2425 *
2426 * This is called after pfnProbe.
2427 *
2428 * @returns VBox status code.
2429 * @param pUVM The user mode VM handle.
2430 * @param pvData Pointer to the instance data.
2431 */
2432 DECLCALLBACKMEMBER(int, pfnInit,(PUVM pUVM, void *pvData));
2433
2434 /**
2435 * Refreshes symbols and stuff following a redetection of the same OS.
2436 *
2437 * This is called after pfnProbe.
2438 *
2439 * @returns VBox status code.
2440 * @param pUVM The user mode VM handle.
2441 * @param pvData Pointer to the instance data.
2442 */
2443 DECLCALLBACKMEMBER(int, pfnRefresh,(PUVM pUVM, void *pvData));
2444
2445 /**
2446 * Terminates an OS when a new (or none) OS has been detected,
2447 * and before destruction.
2448 *
2449 * This is called after pfnProbe and if needed before pfnDestruct.
2450 *
2451 * @param pUVM The user mode VM handle.
2452 * @param pvData Pointer to the instance data.
2453 */
2454 DECLCALLBACKMEMBER(void, pfnTerm,(PUVM pUVM, void *pvData));
2455
2456 /**
2457 * Queries the version of the running OS.
2458 *
2459 * This is only called after pfnInit().
2460 *
2461 * @returns VBox status code.
2462 * @param pUVM The user mode VM handle.
2463 * @param pvData Pointer to the instance data.
2464 * @param pszVersion Where to store the version string.
2465 * @param cchVersion The size of the version string buffer.
2466 */
2467 DECLCALLBACKMEMBER(int, pfnQueryVersion,(PUVM pUVM, void *pvData, char *pszVersion, size_t cchVersion));
2468
2469 /**
2470 * Queries the pointer to a interface.
2471 *
2472 * This is called after pfnProbe.
2473 *
2474 * The returned interface must be valid until pfnDestruct is called. Two calls
2475 * to this method with the same @a enmIf value must return the same pointer.
2476 *
2477 * @returns Pointer to the interface if available, NULL if not available.
2478 * @param pUVM The user mode VM handle.
2479 * @param pvData Pointer to the instance data.
2480 * @param enmIf The interface identifier.
2481 */
2482 DECLCALLBACKMEMBER(void *, pfnQueryInterface,(PUVM pUVM, void *pvData, DBGFOSINTERFACE enmIf));
2483
2484 /**
2485 * Stack unwind assist callback.
2486 *
2487 * This is only called after pfnInit().
2488 *
2489 * @returns VBox status code (allocation error or something of similar fatality).
2490 * @param pUVM The user mode VM handle.
2491 * @param pvData Pointer to the instance data.
2492 * @param idCpu The CPU that's unwinding it's stack.
2493 * @param pFrame The current frame. Okay to modify it a little.
2494 * @param pState The unwind state. Okay to modify it.
2495 * @param pInitialCtx The initial register context.
2496 * @param hAs The address space being used for the unwind.
2497 * @param puScratch Scratch area (initialized to zero, no dtor).
2498 */
2499 DECLCALLBACKMEMBER(int, pfnStackUnwindAssist,(PUVM pUVM, void *pvData, VMCPUID idCpu, PDBGFSTACKFRAME pFrame,
2500 PRTDBGUNWINDSTATE pState, PCCPUMCTX pInitialCtx, RTDBGAS hAs,
2501 uint64_t *puScratch));
2502
2503 /** Trailing magic (DBGFOSREG_MAGIC). */
2504 uint32_t u32EndMagic;
2505} DBGFOSREG;
2506/** Pointer to a Guest OS digger registration record. */
2507typedef DBGFOSREG *PDBGFOSREG;
2508/** Pointer to a const Guest OS digger registration record. */
2509typedef DBGFOSREG const *PCDBGFOSREG;
2510
2511/** Magic value for DBGFOSREG::u32Magic and DBGFOSREG::u32EndMagic. (Hitomi Kanehara) */
2512#define DBGFOSREG_MAGIC 0x19830808
2513
2514
2515/**
2516 * Interface for querying kernel log messages (DBGFOSINTERFACE_DMESG).
2517 */
2518typedef struct DBGFOSIDMESG
2519{
2520 /** Trailing magic (DBGFOSIDMESG_MAGIC). */
2521 uint32_t u32Magic;
2522
2523 /**
2524 * Query the kernel log.
2525 *
2526 * @returns VBox status code.
2527 * @retval VERR_NOT_FOUND if the messages could not be located.
2528 * @retval VERR_INVALID_STATE if the messages was found to have unknown/invalid
2529 * format.
2530 * @retval VERR_BUFFER_OVERFLOW if the buffer isn't large enough, pcbActual
2531 * will be set to the required buffer size. The buffer, however, will
2532 * be filled with as much data as it can hold (properly zero terminated
2533 * of course).
2534 *
2535 * @param pThis Pointer to the interface structure.
2536 * @param pUVM The user mode VM handle.
2537 * @param fFlags Flags reserved for future use, MBZ.
2538 * @param cMessages The number of messages to retrieve, counting from the
2539 * end of the log (i.e. like tail), use UINT32_MAX for all.
2540 * @param pszBuf The output buffer.
2541 * @param cbBuf The buffer size.
2542 * @param pcbActual Where to store the number of bytes actually returned,
2543 * including zero terminator. On VERR_BUFFER_OVERFLOW this
2544 * holds the necessary buffer size. Optional.
2545 */
2546 DECLCALLBACKMEMBER(int, pfnQueryKernelLog,(struct DBGFOSIDMESG *pThis, PUVM pUVM, uint32_t fFlags, uint32_t cMessages,
2547 char *pszBuf, size_t cbBuf, size_t *pcbActual));
2548 /** Trailing magic (DBGFOSIDMESG_MAGIC). */
2549 uint32_t u32EndMagic;
2550} DBGFOSIDMESG;
2551/** Pointer to the interface for query kernel log messages (DBGFOSINTERFACE_DMESG). */
2552typedef DBGFOSIDMESG *PDBGFOSIDMESG;
2553/** Magic value for DBGFOSIDMESG::32Magic and DBGFOSIDMESG::u32EndMagic. (Kenazburo Oe) */
2554#define DBGFOSIDMESG_MAGIC UINT32_C(0x19350131)
2555
2556
2557/**
2558 * Interface for querying Windows NT guest specifics (DBGFOSINTERFACE_WINNT).
2559 */
2560typedef struct DBGFOSIWINNT
2561{
2562 /** Trailing magic (DBGFOSIWINNT_MAGIC). */
2563 uint32_t u32Magic;
2564
2565 /**
2566 * Queries version information.
2567 *
2568 * @returns VBox status code.
2569 * @param pThis Pointer to the interface structure.
2570 * @param pUVM The user mode VM handle.
2571 * @param puVersMajor Where to store the major version part, optional.
2572 * @param puVersMinor Where to store the minor version part, optional.
2573 * @param puBuildNumber Where to store the build number, optional.
2574 * @param pf32Bit Where to store the flag whether this is a 32bit Windows NT, optional.
2575 */
2576 DECLCALLBACKMEMBER(int, pfnQueryVersion,(struct DBGFOSIWINNT *pThis, PUVM pUVM,
2577 uint32_t *puVersMajor, uint32_t *puVersMinor,
2578 uint32_t *puBuildNumber, bool *pf32Bit));
2579
2580 /**
2581 * Queries some base kernel pointers.
2582 *
2583 * @returns VBox status code.
2584 * @param pThis Pointer to the interface structure.
2585 * @param pUVM The user mode VM handle.
2586 * @param pGCPtrKernBase Where to store the kernel base on success.
2587 * @param pGCPtrPsLoadedModuleList Where to store the pointer to the laoded module list head on success.
2588 */
2589 DECLCALLBACKMEMBER(int, pfnQueryKernelPtrs,(struct DBGFOSIWINNT *pThis, PUVM pUVM,
2590 PRTGCUINTPTR pGCPtrKernBase, PRTGCUINTPTR pGCPtrPsLoadedModuleList));
2591
2592 /**
2593 * Queries KPCR and KPCRB pointers for the given vCPU.
2594 *
2595 * @returns VBox status code.
2596 * @param pThis Pointer to the interface structure.
2597 * @param pUVM The user mode VM handle.
2598 * @param idCpu The vCPU to query the KPCR/KPCRB for.
2599 * @param pKpcr Where to store the KPCR pointer on success, optional.
2600 * @param pKpcrb Where to store the KPCR pointer on success, optional.
2601 */
2602 DECLCALLBACKMEMBER(int, pfnQueryKpcrForVCpu,(struct DBGFOSIWINNT *pThis, PUVM pUVM, VMCPUID idCpu,
2603 PRTGCUINTPTR pKpcr, PRTGCUINTPTR pKpcrb));
2604
2605 /**
2606 * Queries the current thread for the given vCPU.
2607 *
2608 * @returns VBox status code.
2609 * @param pThis Pointer to the interface structure.
2610 * @param pUVM The user mode VM handle.
2611 * @param idCpu The vCPU to query the KPCR/KPCRB for.
2612 * @param pCurThrd Where to store the CurrentThread pointer on success.
2613 */
2614 DECLCALLBACKMEMBER(int, pfnQueryCurThrdForVCpu,(struct DBGFOSIWINNT *pThis, PUVM pUVM, VMCPUID idCpu,
2615 PRTGCUINTPTR pCurThrd));
2616
2617 /** Trailing magic (DBGFOSIWINNT_MAGIC). */
2618 uint32_t u32EndMagic;
2619} DBGFOSIWINNT;
2620/** Pointer to the interface for query kernel log messages (DBGFOSINTERFACE_WINNT). */
2621typedef DBGFOSIWINNT *PDBGFOSIWINNT;
2622/** Magic value for DBGFOSIWINNT::32Magic and DBGFOSIWINNT::u32EndMagic. (Dave Cutler) */
2623#define DBGFOSIWINNT_MAGIC UINT32_C(0x19420313)
2624
2625
2626VMMR3DECL(int) DBGFR3OSRegister(PUVM pUVM, PCDBGFOSREG pReg);
2627VMMR3DECL(int) DBGFR3OSDeregister(PUVM pUVM, PCDBGFOSREG pReg);
2628VMMR3DECL(int) DBGFR3OSDetect(PUVM pUVM, char *pszName, size_t cchName);
2629VMMR3DECL(int) DBGFR3OSQueryNameAndVersion(PUVM pUVM, char *pszName, size_t cchName, char *pszVersion, size_t cchVersion);
2630VMMR3DECL(void *) DBGFR3OSQueryInterface(PUVM pUVM, DBGFOSINTERFACE enmIf);
2631
2632
2633VMMR3DECL(int) DBGFR3CoreWrite(PUVM pUVM, const char *pszFilename, bool fReplaceFile);
2634
2635
2636
2637/** @defgroup grp_dbgf_plug_in The DBGF Plug-in Interface
2638 * @{
2639 */
2640
2641/** The plug-in module name prefix. */
2642# define DBGF_PLUG_IN_PREFIX "DbgPlugIn"
2643
2644/** The name of the plug-in entry point (FNDBGFPLUGIN) */
2645# define DBGF_PLUG_IN_ENTRYPOINT "DbgPlugInEntry"
2646
2647/**
2648 * DBGF plug-in operations.
2649 */
2650typedef enum DBGFPLUGINOP
2651{
2652 /** The usual invalid first value. */
2653 DBGFPLUGINOP_INVALID,
2654 /** Initialize the plug-in for a VM, register all the stuff.
2655 * The plug-in will be unloaded on failure.
2656 * uArg: The full VirtualBox version, see VBox/version.h. */
2657 DBGFPLUGINOP_INIT,
2658 /** Terminate the plug-ing for a VM, deregister all the stuff.
2659 * The plug-in will be unloaded after this call regardless of the return
2660 * code. */
2661 DBGFPLUGINOP_TERM,
2662 /** The usual 32-bit hack. */
2663 DBGFPLUGINOP_32BIT_HACK = 0x7fffffff
2664} DBGFPLUGINOP;
2665
2666/**
2667 * DBGF plug-in main entry point.
2668 *
2669 * @returns VBox status code.
2670 *
2671 * @param enmOperation The operation.
2672 * @param pUVM The user mode VM handle. This may be NULL.
2673 * @param uArg Extra argument.
2674 */
2675typedef DECLCALLBACKTYPE(int, FNDBGFPLUGIN,(DBGFPLUGINOP enmOperation, PUVM pUVM, uintptr_t uArg));
2676/** Pointer to a FNDBGFPLUGIN. */
2677typedef FNDBGFPLUGIN *PFNDBGFPLUGIN;
2678
2679/** @copydoc FNDBGFPLUGIN */
2680DECLEXPORT(int) DbgPlugInEntry(DBGFPLUGINOP enmOperation, PUVM pUVM, uintptr_t uArg);
2681
2682VMMR3DECL(int) DBGFR3PlugInLoad(PUVM pUVM, const char *pszPlugIn, char *pszActual, size_t cbActual, PRTERRINFO pErrInfo);
2683VMMR3DECL(int) DBGFR3PlugInUnload(PUVM pUVM, const char *pszName);
2684VMMR3DECL(void) DBGFR3PlugInLoadAll(PUVM pUVM);
2685VMMR3DECL(void) DBGFR3PlugInUnloadAll(PUVM pUVM);
2686
2687/** @} */
2688
2689
2690/** @defgroup grp_dbgf_types The DBGF type system Interface.
2691 * @{
2692 */
2693
2694/** A few forward declarations. */
2695/** Pointer to a type registration structure. */
2696typedef struct DBGFTYPEREG *PDBGFTYPEREG;
2697/** Pointer to a const type registration structure. */
2698typedef const struct DBGFTYPEREG *PCDBGFTYPEREG;
2699/** Pointer to a typed buffer. */
2700typedef struct DBGFTYPEVAL *PDBGFTYPEVAL;
2701
2702/**
2703 * DBGF built-in types.
2704 */
2705typedef enum DBGFTYPEBUILTIN
2706{
2707 /** The usual invalid first value. */
2708 DBGFTYPEBUILTIN_INVALID,
2709 /** Unsigned 8bit integer. */
2710 DBGFTYPEBUILTIN_UINT8,
2711 /** Signed 8bit integer. */
2712 DBGFTYPEBUILTIN_INT8,
2713 /** Unsigned 16bit integer. */
2714 DBGFTYPEBUILTIN_UINT16,
2715 /** Signed 16bit integer. */
2716 DBGFTYPEBUILTIN_INT16,
2717 /** Unsigned 32bit integer. */
2718 DBGFTYPEBUILTIN_UINT32,
2719 /** Signed 32bit integer. */
2720 DBGFTYPEBUILTIN_INT32,
2721 /** Unsigned 64bit integer. */
2722 DBGFTYPEBUILTIN_UINT64,
2723 /** Signed 64bit integer. */
2724 DBGFTYPEBUILTIN_INT64,
2725 /** 32bit Guest pointer */
2726 DBGFTYPEBUILTIN_PTR32,
2727 /** 64bit Guest pointer */
2728 DBGFTYPEBUILTIN_PTR64,
2729 /** Guest pointer - size depends on the guest bitness */
2730 DBGFTYPEBUILTIN_PTR,
2731 /** Type indicating a size, like size_t this can have different sizes
2732 * on 32bit and 64bit systems */
2733 DBGFTYPEBUILTIN_SIZE,
2734 /** 32bit float. */
2735 DBGFTYPEBUILTIN_FLOAT32,
2736 /** 64bit float (also known as double). */
2737 DBGFTYPEBUILTIN_FLOAT64,
2738 /** Compund types like structs and unions. */
2739 DBGFTYPEBUILTIN_COMPOUND,
2740 /** The usual 32-bit hack. */
2741 DBGFTYPEBUILTIN_32BIT_HACK = 0x7fffffff
2742} DBGFTYPEBUILTIN;
2743/** Pointer to a built-in type. */
2744typedef DBGFTYPEBUILTIN *PDBGFTYPEBUILTIN;
2745/** Pointer to a const built-in type. */
2746typedef const DBGFTYPEBUILTIN *PCDBGFTYPEBUILTIN;
2747
2748/**
2749 * DBGF type value buffer.
2750 */
2751typedef union DBGFTYPEVALBUF
2752{
2753 uint8_t u8;
2754 int8_t i8;
2755 uint16_t u16;
2756 int16_t i16;
2757 uint32_t u32;
2758 int32_t i32;
2759 uint64_t u64;
2760 int64_t i64;
2761 float f32;
2762 double f64;
2763 uint64_t size; /* For the built-in size_t which can be either 32-bit or 64-bit. */
2764 RTGCPTR GCPtr;
2765 /** For embedded structs. */
2766 PDBGFTYPEVAL pVal;
2767} DBGFTYPEVALBUF;
2768/** Pointer to a value. */
2769typedef DBGFTYPEVALBUF *PDBGFTYPEVALBUF;
2770
2771/**
2772 * DBGF type value entry.
2773 */
2774typedef struct DBGFTYPEVALENTRY
2775{
2776 /** DBGF built-in type. */
2777 DBGFTYPEBUILTIN enmType;
2778 /** Size of the type. */
2779 size_t cbType;
2780 /** Number of entries, for arrays this can be > 1. */
2781 uint32_t cEntries;
2782 /** Value buffer, depends on whether this is an array. */
2783 union
2784 {
2785 /** Single value. */
2786 DBGFTYPEVALBUF Val;
2787 /** Pointer to the array of values. */
2788 PDBGFTYPEVALBUF pVal;
2789 } Buf;
2790} DBGFTYPEVALENTRY;
2791/** Pointer to a type value entry. */
2792typedef DBGFTYPEVALENTRY *PDBGFTYPEVALENTRY;
2793/** Pointer to a const type value entry. */
2794typedef const DBGFTYPEVALENTRY *PCDBGFTYPEVALENTRY;
2795
2796/**
2797 * DBGF typed value.
2798 */
2799typedef struct DBGFTYPEVAL
2800{
2801 /** Pointer to the registration structure for this type. */
2802 PCDBGFTYPEREG pTypeReg;
2803 /** Number of value entries. */
2804 uint32_t cEntries;
2805 /** Variable sized array of value entries. */
2806 DBGFTYPEVALENTRY aEntries[1];
2807} DBGFTYPEVAL;
2808
2809/**
2810 * DBGF type variant.
2811 */
2812typedef enum DBGFTYPEVARIANT
2813{
2814 /** The usual invalid first value. */
2815 DBGFTYPEVARIANT_INVALID,
2816 /** A struct. */
2817 DBGFTYPEVARIANT_STRUCT,
2818 /** Union. */
2819 DBGFTYPEVARIANT_UNION,
2820 /** Alias for an existing type. */
2821 DBGFTYPEVARIANT_ALIAS,
2822 /** The usual 32-bit hack. */
2823 DBGFTYPEVARIANT_32BIT_HACK = 0x7fffffff
2824} DBGFTYPEVARIANT;
2825
2826/** @name DBGFTYPEREGMEMBER Flags.
2827 * @{ */
2828/** The member is an array with a fixed size. */
2829# define DBGFTYPEREGMEMBER_F_ARRAY RT_BIT_32(0)
2830/** The member denotes a pointer. */
2831# define DBGFTYPEREGMEMBER_F_POINTER RT_BIT_32(1)
2832/** @} */
2833
2834/**
2835 * DBGF type member.
2836 */
2837typedef struct DBGFTYPEREGMEMBER
2838{
2839 /** Name of the member. */
2840 const char *pszName;
2841 /** Flags for this member, see DBGFTYPEREGMEMBER_F_XXX. */
2842 uint32_t fFlags;
2843 /** Type identifier. */
2844 const char *pszType;
2845 /** The number of elements in the array, only valid for arrays. */
2846 uint32_t cElements;
2847} DBGFTYPEREGMEMBER;
2848/** Pointer to a member. */
2849typedef DBGFTYPEREGMEMBER *PDBGFTYPEREGMEMBER;
2850/** Pointer to a const member. */
2851typedef const DBGFTYPEREGMEMBER *PCDBGFTYPEREGMEMBER;
2852
2853/** @name DBGFTYPEREG Flags.
2854 * @{ */
2855/** The type is a packed structure. */
2856# define DBGFTYPEREG_F_PACKED RT_BIT_32(0)
2857/** @} */
2858
2859/**
2860 * New type registration structure.
2861 */
2862typedef struct DBGFTYPEREG
2863{
2864 /** Name of the type. */
2865 const char *pszType;
2866 /** The type variant. */
2867 DBGFTYPEVARIANT enmVariant;
2868 /** Some registration flags, see DBGFTYPEREG_F_XXX. */
2869 uint32_t fFlags;
2870 /** Number of members this type has, only valid for structs or unions. */
2871 uint32_t cMembers;
2872 /** Pointer to the member fields, only valid for structs or unions. */
2873 PCDBGFTYPEREGMEMBER paMembers;
2874 /** Name of the aliased type for aliases. */
2875 const char *pszAliasedType;
2876} DBGFTYPEREG;
2877
2878/**
2879 * DBGF typed value dumper callback.
2880 *
2881 * @returns VBox status code. Any non VINF_SUCCESS status code will abort the dumping.
2882 *
2883 * @param off The byte offset of the entry from the start of the type.
2884 * @param pszField The name of the field for the value.
2885 * @param iLvl The current level.
2886 * @param enmType The type enum.
2887 * @param cbType Size of the type.
2888 * @param pValBuf Pointer to the value buffer.
2889 * @param cValBufs Number of value buffers (for arrays).
2890 * @param pvUser Opaque user data.
2891 */
2892typedef DECLCALLBACKTYPE(int, FNDBGFR3TYPEVALDUMP,(uint32_t off, const char *pszField, uint32_t iLvl,
2893 DBGFTYPEBUILTIN enmType, size_t cbType,
2894 PDBGFTYPEVALBUF pValBuf, uint32_t cValBufs, void *pvUser));
2895/** Pointer to a FNDBGFR3TYPEVALDUMP. */
2896typedef FNDBGFR3TYPEVALDUMP *PFNDBGFR3TYPEVALDUMP;
2897
2898/**
2899 * DBGF type information dumper callback.
2900 *
2901 * @returns VBox status code. Any non VINF_SUCCESS status code will abort the dumping.
2902 *
2903 * @param off The byte offset of the entry from the start of the type.
2904 * @param pszField The name of the field for the value.
2905 * @param iLvl The current level.
2906 * @param pszType The type of the field.
2907 * @param fTypeFlags Flags for this type, see DBGFTYPEREGMEMBER_F_XXX.
2908 * @param cElements Number of for the field ( > 0 for arrays).
2909 * @param pvUser Opaque user data.
2910 */
2911typedef DECLCALLBACKTYPE(int, FNDBGFR3TYPEDUMP,(uint32_t off, const char *pszField, uint32_t iLvl,
2912 const char *pszType, uint32_t fTypeFlags,
2913 uint32_t cElements, void *pvUser));
2914/** Pointer to a FNDBGFR3TYPEDUMP. */
2915typedef FNDBGFR3TYPEDUMP *PFNDBGFR3TYPEDUMP;
2916
2917VMMR3DECL(int) DBGFR3TypeRegister( PUVM pUVM, uint32_t cTypes, PCDBGFTYPEREG paTypes);
2918VMMR3DECL(int) DBGFR3TypeDeregister(PUVM pUVM, const char *pszType);
2919VMMR3DECL(int) DBGFR3TypeQueryReg( PUVM pUVM, const char *pszType, PCDBGFTYPEREG *ppTypeReg);
2920
2921VMMR3DECL(int) DBGFR3TypeQuerySize( PUVM pUVM, const char *pszType, size_t *pcbType);
2922VMMR3DECL(int) DBGFR3TypeSetSize( PUVM pUVM, const char *pszType, size_t cbType);
2923VMMR3DECL(int) DBGFR3TypeDumpEx( PUVM pUVM, const char *pszType, uint32_t fFlags,
2924 uint32_t cLvlMax, PFNDBGFR3TYPEDUMP pfnDump, void *pvUser);
2925VMMR3DECL(int) DBGFR3TypeQueryValByType(PUVM pUVM, PCDBGFADDRESS pAddress, const char *pszType,
2926 PDBGFTYPEVAL *ppVal);
2927VMMR3DECL(void) DBGFR3TypeValFree(PDBGFTYPEVAL pVal);
2928VMMR3DECL(int) DBGFR3TypeValDumpEx(PUVM pUVM, PCDBGFADDRESS pAddress, const char *pszType, uint32_t fFlags,
2929 uint32_t cLvlMax, FNDBGFR3TYPEVALDUMP pfnDump, void *pvUser);
2930
2931/** @} */
2932
2933
2934/** @defgroup grp_dbgf_flow The DBGF control flow graph Interface.
2935 * @{
2936 */
2937
2938/** A DBGF control flow graph handle. */
2939typedef struct DBGFFLOWINT *DBGFFLOW;
2940/** Pointer to a DBGF control flow graph handle. */
2941typedef DBGFFLOW *PDBGFFLOW;
2942/** A DBGF control flow graph basic block handle. */
2943typedef struct DBGFFLOWBBINT *DBGFFLOWBB;
2944/** Pointer to a DBGF control flow graph basic block handle. */
2945typedef DBGFFLOWBB *PDBGFFLOWBB;
2946/** A DBGF control flow graph branch table handle. */
2947typedef struct DBGFFLOWBRANCHTBLINT *DBGFFLOWBRANCHTBL;
2948/** Pointer to a DBGF flow control graph branch table handle. */
2949typedef DBGFFLOWBRANCHTBL *PDBGFFLOWBRANCHTBL;
2950/** A DBGF control flow graph iterator. */
2951typedef struct DBGFFLOWITINT *DBGFFLOWIT;
2952/** Pointer to a control flow graph iterator. */
2953typedef DBGFFLOWIT *PDBGFFLOWIT;
2954/** A DBGF control flow graph branch table iterator. */
2955typedef struct DBGFFLOWBRANCHTBLITINT *DBGFFLOWBRANCHTBLIT;
2956/** Pointer to a control flow graph branch table iterator. */
2957typedef DBGFFLOWBRANCHTBLIT *PDBGFFLOWBRANCHTBLIT;
2958
2959/** @name DBGFFLOWBB Flags.
2960 * @{ */
2961/** The basic block is the entry into the owning control flow graph. */
2962#define DBGF_FLOW_BB_F_ENTRY RT_BIT_32(0)
2963/** The basic block was not populated because the limit was reached. */
2964#define DBGF_FLOW_BB_F_EMPTY RT_BIT_32(1)
2965/** The basic block is not complete because an error happened during disassembly. */
2966#define DBGF_FLOW_BB_F_INCOMPLETE_ERR RT_BIT_32(2)
2967/** The basic block is reached through a branch table. */
2968#define DBGF_FLOW_BB_F_BRANCH_TABLE RT_BIT_32(3)
2969/** The basic block consists only of a single call instruction because
2970 * DBGF_FLOW_CREATE_F_CALL_INSN_SEPARATE_BB was given. */
2971#define DBGF_FLOW_BB_F_CALL_INSN RT_BIT_32(4)
2972/** The branch target of the call instruction could be deduced and can be queried with
2973 * DBGFR3FlowBbGetBranchAddress(). May only be available when DBGF_FLOW_BB_F_CALL_INSN
2974 * is set. */
2975#define DBGF_FLOW_BB_F_CALL_INSN_TARGET_KNOWN RT_BIT_32(5)
2976/** @} */
2977
2978/** @name Flags controlling the creating of a control flow graph.
2979 * @{ */
2980/** Default options. */
2981#define DBGF_FLOW_CREATE_F_DEFAULT 0
2982/** Tries to resolve indirect branches, useful for code using
2983 * jump tables generated for large switch statements by some compilers. */
2984#define DBGF_FLOW_CREATE_F_TRY_RESOLVE_INDIRECT_BRANCHES RT_BIT_32(0)
2985/** Call instructions are placed in a separate basic block. */
2986#define DBGF_FLOW_CREATE_F_CALL_INSN_SEPARATE_BB RT_BIT_32(1)
2987/** @} */
2988
2989/**
2990 * DBGF control graph basic block end type.
2991 */
2992typedef enum DBGFFLOWBBENDTYPE
2993{
2994 /** Invalid type. */
2995 DBGFFLOWBBENDTYPE_INVALID = 0,
2996 /** Basic block is the exit block and has no successor. */
2997 DBGFFLOWBBENDTYPE_EXIT,
2998 /** Basic block is the last disassembled block because the
2999 * maximum amount to disassemble was reached but is not an
3000 * exit block - no successors.
3001 */
3002 DBGFFLOWBBENDTYPE_LAST_DISASSEMBLED,
3003 /** Unconditional control flow change because the successor is referenced by multiple
3004 * basic blocks. - 1 successor. */
3005 DBGFFLOWBBENDTYPE_UNCOND,
3006 /** Unconditional control flow change because of an direct branch - 1 successor. */
3007 DBGFFLOWBBENDTYPE_UNCOND_JMP,
3008 /** Unconditional control flow change because of an indirect branch - n successors. */
3009 DBGFFLOWBBENDTYPE_UNCOND_INDIRECT_JMP,
3010 /** Conditional control flow change - 2 successors. */
3011 DBGFFLOWBBENDTYPE_COND,
3012 /** 32bit hack. */
3013 DBGFFLOWBBENDTYPE_32BIT_HACK = 0x7fffffff
3014} DBGFFLOWBBENDTYPE;
3015
3016/**
3017 * DBGF control flow graph iteration order.
3018 */
3019typedef enum DBGFFLOWITORDER
3020{
3021 /** Invalid order. */
3022 DBGFFLOWITORDER_INVALID = 0,
3023 /** From lowest to highest basic block start address. */
3024 DBGFFLOWITORDER_BY_ADDR_LOWEST_FIRST,
3025 /** From highest to lowest basic block start address. */
3026 DBGFFLOWITORDER_BY_ADDR_HIGHEST_FIRST,
3027 /** Depth first traversing starting from the entry block. */
3028 DBGFFLOWITORDER_DEPTH_FRIST,
3029 /** Breadth first traversing starting from the entry block. */
3030 DBGFFLOWITORDER_BREADTH_FIRST,
3031 /** Usual 32bit hack. */
3032 DBGFFLOWITORDER_32BIT_HACK = 0x7fffffff
3033} DBGFFLOWITORDER;
3034/** Pointer to a iteration order enum. */
3035typedef DBGFFLOWITORDER *PDBGFFLOWITORDER;
3036
3037
3038VMMR3DECL(int) DBGFR3FlowCreate(PUVM pUVM, VMCPUID idCpu, PDBGFADDRESS pAddressStart, uint32_t cbDisasmMax,
3039 uint32_t fFlagsFlow, uint32_t fFlagsDisasm, PDBGFFLOW phFlow);
3040VMMR3DECL(uint32_t) DBGFR3FlowRetain(DBGFFLOW hFlow);
3041VMMR3DECL(uint32_t) DBGFR3FlowRelease(DBGFFLOW hFlow);
3042VMMR3DECL(int) DBGFR3FlowQueryStartBb(DBGFFLOW hFlow, PDBGFFLOWBB phFlowBb);
3043VMMR3DECL(int) DBGFR3FlowQueryBbByAddress(DBGFFLOW hFlow, PDBGFADDRESS pAddr, PDBGFFLOWBB phFlowBb);
3044VMMR3DECL(int) DBGFR3FlowQueryBranchTblByAddress(DBGFFLOW hFlow, PDBGFADDRESS pAddr, PDBGFFLOWBRANCHTBL phFlowBranchTbl);
3045VMMR3DECL(uint32_t) DBGFR3FlowGetBbCount(DBGFFLOW hFlow);
3046VMMR3DECL(uint32_t) DBGFR3FlowGetBranchTblCount(DBGFFLOW hFlow);
3047VMMR3DECL(uint32_t) DBGFR3FlowGetCallInsnCount(DBGFFLOW hFlow);
3048
3049VMMR3DECL(uint32_t) DBGFR3FlowBbRetain(DBGFFLOWBB hFlowBb);
3050VMMR3DECL(uint32_t) DBGFR3FlowBbRelease(DBGFFLOWBB hFlowBb);
3051VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetStartAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrStart);
3052VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetEndAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrEnd);
3053VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetBranchAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrTarget);
3054VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBbGetFollowingAddress(DBGFFLOWBB hFlowBb, PDBGFADDRESS pAddrFollow);
3055VMMR3DECL(DBGFFLOWBBENDTYPE) DBGFR3FlowBbGetType(DBGFFLOWBB hFlowBb);
3056VMMR3DECL(uint32_t) DBGFR3FlowBbGetInstrCount(DBGFFLOWBB hFlowBb);
3057VMMR3DECL(uint32_t) DBGFR3FlowBbGetFlags(DBGFFLOWBB hFlowBb);
3058VMMR3DECL(int) DBGFR3FlowBbQueryBranchTbl(DBGFFLOWBB hFlowBb, PDBGFFLOWBRANCHTBL phBranchTbl);
3059VMMR3DECL(int) DBGFR3FlowBbQueryError(DBGFFLOWBB hFlowBb, const char **ppszErr);
3060VMMR3DECL(int) DBGFR3FlowBbQueryInstr(DBGFFLOWBB hFlowBb, uint32_t idxInstr, PDBGFADDRESS pAddrInstr,
3061 uint32_t *pcbInstr, const char **ppszInstr);
3062VMMR3DECL(int) DBGFR3FlowBbQuerySuccessors(DBGFFLOWBB hFlowBb, PDBGFFLOWBB phFlowBbFollow,
3063 PDBGFFLOWBB phFlowBbTarget);
3064VMMR3DECL(uint32_t) DBGFR3FlowBbGetRefBbCount(DBGFFLOWBB hFlowBb);
3065VMMR3DECL(int) DBGFR3FlowBbGetRefBb(DBGFFLOWBB hFlowBb, PDBGFFLOWBB pahFlowBbRef, uint32_t cRef);
3066
3067VMMR3DECL(uint32_t) DBGFR3FlowBranchTblRetain(DBGFFLOWBRANCHTBL hFlowBranchTbl);
3068VMMR3DECL(uint32_t) DBGFR3FlowBranchTblRelease(DBGFFLOWBRANCHTBL hFlowBranchTbl);
3069VMMR3DECL(uint32_t) DBGFR3FlowBranchTblGetSlots(DBGFFLOWBRANCHTBL hFlowBranchTbl);
3070VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBranchTblGetStartAddress(DBGFFLOWBRANCHTBL hFlowBranchTbl, PDBGFADDRESS pAddrStart);
3071VMMR3DECL(PDBGFADDRESS) DBGFR3FlowBranchTblGetAddrAtSlot(DBGFFLOWBRANCHTBL hFlowBranchTbl, uint32_t idxSlot, PDBGFADDRESS pAddrSlot);
3072VMMR3DECL(int) DBGFR3FlowBranchTblQueryAddresses(DBGFFLOWBRANCHTBL hFlowBranchTbl, PDBGFADDRESS paAddrs, uint32_t cAddrs);
3073
3074VMMR3DECL(int) DBGFR3FlowItCreate(DBGFFLOW hFlow, DBGFFLOWITORDER enmOrder, PDBGFFLOWIT phFlowIt);
3075VMMR3DECL(void) DBGFR3FlowItDestroy(DBGFFLOWIT hFlowIt);
3076VMMR3DECL(DBGFFLOWBB) DBGFR3FlowItNext(DBGFFLOWIT hFlowIt);
3077VMMR3DECL(int) DBGFR3FlowItReset(DBGFFLOWIT hFlowIt);
3078
3079VMMR3DECL(int) DBGFR3FlowBranchTblItCreate(DBGFFLOW hFlow, DBGFFLOWITORDER enmOrder, PDBGFFLOWBRANCHTBLIT phFlowBranchTblIt);
3080VMMR3DECL(void) DBGFR3FlowBranchTblItDestroy(DBGFFLOWBRANCHTBLIT hFlowBranchTblIt);
3081VMMR3DECL(DBGFFLOWBRANCHTBL) DBGFR3FlowBranchTblItNext(DBGFFLOWBRANCHTBLIT hFlowBranchTblIt);
3082VMMR3DECL(int) DBGFR3FlowBranchTblItReset(DBGFFLOWBRANCHTBLIT hFlowBranchTblIt);
3083
3084/** @} */
3085
3086
3087/** @defgroup grp_dbgf_misc Misc DBGF interfaces.
3088 * @{ */
3089VMMR3DECL(VBOXSTRICTRC) DBGFR3ReportBugCheck(PVM pVM, PVMCPU pVCpu, DBGFEVENTTYPE enmEvent, uint64_t uBugCheck,
3090 uint64_t uP1, uint64_t uP2, uint64_t uP3, uint64_t uP4);
3091VMMR3DECL(int) DBGFR3FormatBugCheck(PUVM pUVM, char *pszDetails, size_t cbDetails,
3092 uint64_t uP0, uint64_t uP1, uint64_t uP2, uint64_t uP3, uint64_t uP4);
3093/** @} */
3094#endif /* IN_RING3 */
3095
3096
3097/** @defgroup grp_dbgf_tracer DBGF event tracing.
3098 * @{ */
3099#ifdef IN_RING3
3100VMMR3_INT_DECL(int) DBGFR3TracerRegisterEvtSrc(PVM pVM, const char *pszName, PDBGFTRACEREVTSRC phEvtSrc);
3101VMMR3_INT_DECL(int) DBGFR3TracerDeregisterEvtSrc(PVM pVM, DBGFTRACEREVTSRC hEvtSrc);
3102VMMR3_INT_DECL(int) DBGFR3TracerEvtIoPortCreate(PVM pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTIOPORT cPorts, uint32_t fFlags,
3103 uint32_t iPciRegion);
3104VMMR3_INT_DECL(int) DBGFR3TracerEvtMmioCreate(PVM pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS cbRegion, uint32_t fFlags,
3105 uint32_t iPciRegion);
3106#endif
3107
3108VMM_INT_DECL(int) DBGFTracerEvtMmioMap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS GCPhysMmio);
3109VMM_INT_DECL(int) DBGFTracerEvtMmioUnmap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion);
3110VMM_INT_DECL(int) DBGFTracerEvtMmioRead(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS offMmio, const void *pvVal, size_t cbVal);
3111VMM_INT_DECL(int) DBGFTracerEvtMmioWrite(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS offMmio, const void *pvVal, size_t cbVal);
3112VMM_INT_DECL(int) DBGFTracerEvtMmioFill(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hRegion, RTGCPHYS offMmio, uint32_t u32Item, uint32_t cbItem, uint32_t cItems);
3113VMM_INT_DECL(int) DBGFTracerEvtIoPortMap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT IoPortBase);
3114VMM_INT_DECL(int) DBGFTracerEvtIoPortUnmap(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts);
3115VMM_INT_DECL(int) DBGFTracerEvtIoPortRead(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pvVal, size_t cbVal);
3116VMM_INT_DECL(int) DBGFTracerEvtIoPortReadStr(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pv, size_t cb,
3117 uint32_t cTransfersReq, uint32_t cTransfersRet);
3118VMM_INT_DECL(int) DBGFTracerEvtIoPortWrite(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pvVal, size_t cbVal);
3119VMM_INT_DECL(int) DBGFTracerEvtIoPortWriteStr(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, uint64_t hIoPorts, RTIOPORT offPort, const void *pv, size_t cb,
3120 uint32_t cTransfersReq, uint32_t cTransfersRet);
3121VMM_INT_DECL(int) DBGFTracerEvtIrq(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, int32_t iIrq, int32_t fIrqLvl);
3122VMM_INT_DECL(int) DBGFTracerEvtIoApicMsi(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, RTGCPHYS GCPhys, uint32_t u32Val);
3123VMM_INT_DECL(int) DBGFTracerEvtGCPhysRead(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, RTGCPHYS GCPhys, const void *pvBuf, size_t cbRead);
3124VMM_INT_DECL(int) DBGFTracerEvtGCPhysWrite(PVMCC pVM, DBGFTRACEREVTSRC hEvtSrc, RTGCPHYS GCPhys, const void *pvBuf, size_t cbWrite);
3125/** @} */
3126
3127
3128/** @defgroup grp_dbgf_sample_report DBGF sample report.
3129 * @{ */
3130
3131/**
3132 * Callback which provides progress information about a currently running
3133 * lengthy operation.
3134 *
3135 * @return VBox status code.
3136 * @retval VERR_DBGF_CANCELLED to cancel the operation.
3137 * @param pvUser The opaque user data associated with this interface.
3138 * @param uPercentage Completion percentage.
3139 */
3140typedef DECLCALLBACKTYPE(int, FNDBGFPROGRESS,(void *pvUser, unsigned uPercentage));
3141/** Pointer to FNDBGFPROGRESS() */
3142typedef FNDBGFPROGRESS *PFNDBGFPROGRESS;
3143
3144/** @name Flags to pass to DBGFR3SampleReportCreate().
3145 * @{ */
3146/** The report creates the call stack in reverse order (bottom to top). */
3147#define DBGF_SAMPLE_REPORT_F_STACK_REVERSE RT_BIT(0)
3148/** Mask containing the valid flags. */
3149#define DBGF_SAMPLE_REPORT_F_VALID_MASK UINT32_C(0x00000001)
3150/** @} */
3151
3152VMMR3DECL(int) DBGFR3SampleReportCreate(PUVM pUVM, uint32_t cSampleIntervalMs, uint32_t fFlags, PDBGFSAMPLEREPORT phSample);
3153VMMR3DECL(uint32_t) DBGFR3SampleReportRetain(DBGFSAMPLEREPORT hSample);
3154VMMR3DECL(uint32_t) DBGFR3SampleReportRelease(DBGFSAMPLEREPORT hSample);
3155VMMR3DECL(int) DBGFR3SampleReportStart(DBGFSAMPLEREPORT hSample, uint64_t cSampleUs, PFNDBGFPROGRESS pfnProgress, void *pvUser);
3156VMMR3DECL(int) DBGFR3SampleReportStop(DBGFSAMPLEREPORT hSample);
3157VMMR3DECL(int) DBGFR3SampleReportDumpToFile(DBGFSAMPLEREPORT hSample, const char *pszFilename);
3158/** @} */
3159
3160/** @} */
3161
3162RT_C_DECLS_END
3163
3164#endif /* !VBOX_INCLUDED_vmm_dbgf_h */
3165
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette