dbgf.h@ 6981

Last change on this file since 6981 was 5999, checked in by vboxsync, 17 years ago
The Giant CDDL Dual-License Header Change.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 50.9 KB

Line
1	/** @file
2	* DBGF - Debugging Facility.
3	*/
4
5	/*
6	* Copyright (C) 2006-2007 innotek GmbH
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_dbgf_h
27	#define ___VBox_dbgf_h
28
29	#include <VBox/cdefs.h>
30	#include <VBox/types.h>
31	#include <VBox/vmm.h>
32	#include <VBox/log.h> /* LOG_ENABLED */
33
34	#include <iprt/stdarg.h>
35
36	__BEGIN_DECLS
37
38
39	/** @defgroup grp_dbgf The Debugging Facility API
40	* @{
41	*/
42
43	#ifdef IN_GC
44	/** @addgroup grp_dbgf_gc The GC DBGF API
45	* @ingroup grp_dbgf
46	* @{
47	*/
48
49	/**
50	* \#DB (Debug event) handler.
51	*
52	* @returns VBox status code.
53	* VINF_SUCCESS means we completely handled this trap,
54	* other codes are passed execution to host context.
55	*
56	* @param pVM The VM handle.
57	* @param pRegFrame Pointer to the register frame for the trap.
58	* @param uDr6 The DR6 register value.
59	*/
60	DBGFGCDECL(int) DBGFGCTrap01Handler(PVM pVM, PCPUMCTXCORE pRegFrame, RTUINTREG uDr6);
61
62	/**
63	* \#BP (Breakpoint) handler.
64	*
65	* @returns VBox status code.
66	* VINF_SUCCESS means we completely handled this trap,
67	* other codes are passed execution to host context.
68	*
69	* @param pVM The VM handle.
70	* @param pRegFrame Pointer to the register frame for the trap.
71	*/
72	DBGFGCDECL(int) DBGFGCTrap03Handler(PVM pVM, PCPUMCTXCORE pRegFrame);
73
74	/** @} */
75	#endif
76
77	#ifdef IN_RING0
78	/** @addgroup grp_dbgf_gc The R0 DBGF API
79	* @ingroup grp_dbgf
80	* @{
81	*/
82
83	/**
84	* \#DB (Debug event) handler.
85	*
86	* @returns VBox status code.
87	* VINF_SUCCESS means we completely handled this trap,
88	* other codes are passed execution to host context.
89	*
90	* @param pVM The VM handle.
91	* @param pRegFrame Pointer to the register frame for the trap.
92	* @param uDr6 The DR6 register value.
93	*/
94	DBGFR0DECL(int) DBGFR0Trap01Handler(PVM pVM, PCPUMCTXCORE pRegFrame, RTUINTREG uDr6);
95
96	/**
97	* \#BP (Breakpoint) handler.
98	*
99	* @returns VBox status code.
100	* VINF_SUCCESS means we completely handled this trap,
101	* other codes are passed execution to host context.
102	*
103	* @param pVM The VM handle.
104	* @param pRegFrame Pointer to the register frame for the trap.
105	*/
106	DBGFR0DECL(int) DBGFR0Trap03Handler(PVM pVM, PCPUMCTXCORE pRegFrame);
107
108	/** @} */
109	#endif
110
111
112
113	/**
114	* Mixed address.
115	*/
116	typedef struct DBGFADDRESS
117	{
118	/** The flat address. */
119	RTGCUINTPTR FlatPtr;
120	/** The selector offset address. */
121	RTGCUINTPTR off;
122	/** The selector. DBGF_SEL_FLAT is a legal value. */
123	RTSEL Sel;
124	/** Flags describing further details about the address. */
125	uint16_t fFlags;
126	} DBGFADDRESS;
127	/** Pointer to a mixed address. */
128	typedef DBGFADDRESS *PDBGFADDRESS;
129	/** Pointer to a const mixed address. */
130	typedef const DBGFADDRESS *PCDBGFADDRESS;
131
132	/** @name DBGFADDRESS Flags.
133	* @{ */
134	/** A 16:16 far address. */
135	#define DBGFADDRESS_FLAGS_FAR16 0
136	/** A 16:32 far address. */
137	#define DBGFADDRESS_FLAGS_FAR32 1
138	/** A 16:64 far address. */
139	#define DBGFADDRESS_FLAGS_FAR64 2
140	/** A flat address. */
141	#define DBGFADDRESS_FLAGS_FLAT 3
142	/** A physical address. */
143	#define DBGFADDRESS_FLAGS_PHYS 4
144	/** The address type mask. */
145	#define DBGFADDRESS_FLAGS_TYPE_MASK 7
146
147	/** Set if the address is valid. */
148	#define DBGFADDRESS_FLAGS_VALID RT_BIT(3)
149
150	/** The address is within the hypervisor memoary area (HMA).
151	* If not set, the address can be assumed to be a guest address. */
152	#define DBGFADDRESS_FLAGS_HMA RT_BIT(4)
153
154	/** Checks if the mixed address is flat or not. */
155	#define DBGFADDRESS_IS_FLAT(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FLAT )
156	/** Checks if the mixed address is flat or not. */
157	#define DBGFADDRESS_IS_PHYS(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_PHYS )
158	/** Checks if the mixed address is far 16:16 or not. */
159	#define DBGFADDRESS_IS_FAR16(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR16 )
160	/** Checks if the mixed address is far 16:32 or not. */
161	#define DBGFADDRESS_IS_FAR32(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR32 )
162	/** Checks if the mixed address is far 16:64 or not. */
163	#define DBGFADDRESS_IS_FAR64(pAddress) ( ((pAddress)->fFlags & DBGFADDRESS_FLAGS_TYPE_MASK) == DBGFADDRESS_FLAGS_FAR64 )
164	/** Checks if the mixed address is valid. */
165	#define DBGFADDRESS_IS_VALID(pAddress) ( !!((pAddress)->fFlags & DBGFADDRESS_FLAGS_VALID) )
166	/** Checks if the address is flagged as within the HMA. */
167	#define DBGFADDRESS_IS_HMA(pAddress) ( !!((pAddress)->fFlags & DBGFADDRESS_FLAGS_HMA) )
168	/** @} */
169
170	/**
171	* Creates a mixed address from a Sel:off pair.
172	*
173	* @returns VBox status code.
174	* @param pVM The VM handle.
175	* @param pAddress Where to store the mixed address.
176	* @param Sel The selector part.
177	* @param off The offset part.
178	*/
179	DBGFR3DECL(int) DBGFR3AddrFromSelOff(PVM pVM, PDBGFADDRESS pAddress, RTSEL Sel, RTUINTPTR off);
180
181	/**
182	* Creates a mixed address from a flat address.
183	*
184	* @param pVM The VM handle.
185	* @param pAddress Where to store the mixed address.
186	* @param FlatPtr The flat pointer.
187	*/
188	DBGFR3DECL(void) DBGFR3AddrFromFlat(PVM pVM, PDBGFADDRESS pAddress, RTGCUINTPTR FlatPtr);
189
190	/**
191	* Creates a mixed address from a guest physical address.
192	*
193	* @param pVM The VM handle.
194	* @param pAddress Where to store the mixed address.
195	* @param PhysAddr The guest physical address.
196	*/
197	DBGFR3DECL(void) DBGFR3AddrFromPhys(PVM pVM, PDBGFADDRESS pAddress, RTGCPHYS PhysAddr);
198
199	/**
200	* Checks if the specified address is valid (checks the structure pointer too).
201	*
202	* @returns true if valid.
203	* @returns false if invalid.
204	* @param pVM The VM handle.
205	* @param pAddress The address to validate.
206	*/
207	DBGFR3DECL(bool) DBGFR3AddrIsValid(PVM pVM, PCDBGFADDRESS pAddress);
208
209
210
211
212	/**
213	* VMM Debug Event Type.
214	*/
215	typedef enum DBGFEVENTTYPE
216	{
217	/** Halt completed.
218	* This notifies that a halt command have been successfully completed.
219	*/
220	DBGFEVENT_HALT_DONE = 0,
221	/** Detach completed.
222	* This notifies that the detach command have been successfully completed.
223	*/
224	DBGFEVENT_DETACH_DONE,
225	/** The command from the debugger is not recognized.
226	* This means internal error or half implemented features.
227	*/
228	DBGFEVENT_INVALID_COMMAND,
229
230
231	/** Fatal error.
232	* This notifies a fatal error in the VMM and that the debugger get's a
233	* chance to first hand information about the the problem.
234	*/
235	DBGFEVENT_FATAL_ERROR = 100,
236	/** Breakpoint Hit.
237	* This notifies that a breakpoint installed by the debugger was hit. The
238	* identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
239	*/
240	DBGFEVENT_BREAKPOINT,
241	/** Breakpoint Hit in the Hypervisor.
242	* This notifies that a breakpoint installed by the debugger was hit. The
243	* identifier of the breakpoint can be found in the DBGFEVENT::u::Bp::iBp member.
244	*/
245	DBGFEVENT_BREAKPOINT_HYPER,
246	/** Assertion in the Hypervisor (breakpoint instruction).
247	* This notifies that a breakpoint instruction was hit in the hypervisor context.
248	*/
249	DBGFEVENT_ASSERTION_HYPER,
250	/** Single Stepped.
251	* This notifies that a single step operation was completed.
252	*/
253	DBGFEVENT_STEPPED,
254	/** Single Stepped.
255	* This notifies that a hypervisor single step operation was completed.
256	*/
257	DBGFEVENT_STEPPED_HYPER,
258	/** The developer have used the DBGFSTOP macro or the PDMDeviceDBGFSTOP function
259	* to bring up the debugger at a specific place.
260	*/
261	DBGFEVENT_DEV_STOP,
262	/** The VM is terminating.
263	* When this notification is received, the debugger thread should detach ASAP.
264	*/
265	DBGFEVENT_TERMINATING,
266
267	/** The usual 32-bit hack. */
268	DBGFEVENT_32BIT_HACK = 0x7fffffff
269	} DBGFEVENTTYPE;
270
271
272	/**
273	* The context of an event.
274	*/
275	typedef enum DBGFEVENTCTX
276	{
277	/** The usual invalid entry. */
278	DBGFEVENTCTX_INVALID = 0,
279	/** Raw mode. */
280	DBGFEVENTCTX_RAW,
281	/** Recompiled mode. */
282	DBGFEVENTCTX_REM,
283	/** VMX / AVT mode. */
284	DBGFEVENTCTX_HWACCL,
285	/** Hypervisor context. */
286	DBGFEVENTCTX_HYPER,
287	/** Other mode */
288	DBGFEVENTCTX_OTHER,
289
290	/** The usual 32-bit hack */
291	DBGFEVENTCTX_32BIT_HACK = 0x7fffffff
292	} DBGFEVENTCTX;
293
294	/**
295	* VMM Debug Event.
296	*/
297	typedef struct DBGFEVENT
298	{
299	/** Type. */
300	DBGFEVENTTYPE enmType;
301	/** Context */
302	DBGFEVENTCTX enmCtx;
303	/** Type specific data. */
304	union
305	{
306	/** Fatal error details. */
307	struct
308	{
309	/** The GC return code. */
310	int rc;
311	} FatalError;
312
313	/** Source location. */
314	struct
315	{
316	/** File name. */
317	R3PTRTYPE(const char *) pszFile;
318	/** Function name. */
319	R3PTRTYPE(const char *) pszFunction;
320	/** Message. */
321	R3PTRTYPE(const char *) pszMessage;
322	/** Line number. */
323	unsigned uLine;
324	} Src;
325
326	/** Assertion messages. */
327	struct
328	{
329	/** The first message. */
330	R3PTRTYPE(const char *) pszMsg1;
331	/** The second message. */
332	R3PTRTYPE(const char *) pszMsg2;
333	} Assert;
334
335	/** Breakpoint. */
336	struct DBGFEVENTBP
337	{
338	/** The identifier of the breakpoint which was hit. */
339	RTUINT iBp;
340	} Bp;
341	/** Padding for ensuring that the structure is 8 byte aligned. */
342	uint64_t au64Padding[4];
343	} u;
344	} DBGFEVENT;
345	/** Pointer to VMM Debug Event. */
346	typedef DBGFEVENT *PDBGFEVENT;
347	/** Pointer to const VMM Debug Event. */
348	typedef const DBGFEVENT *PCDBGFEVENT;
349
350
351	/** @def DBGFSTOP
352	* Stops the debugger raising a DBGFEVENT_DEVELOPER_STOP event.
353	*
354	* @returns VBox status code which must be propagated up to EM if not VINF_SUCCESS.
355	* @param pVM VM Handle.
356	*/
357	#ifdef VBOX_STRICT
358	# define DBGFSTOP(pVM) DBGFR3EventSrc(pVM, DBGFEVENT_DEV_STOP, __FILE__, __LINE__, __PRETTY_FUNCTION__, NULL)
359	#else
360	# define DBGFSTOP(pVM) VINF_SUCCESS
361	#endif
362
363	/**
364	* Initializes the DBGF.
365	*
366	* @returns VBox status code.
367	* @param pVM VM handle.
368	*/
369	DBGFR3DECL(int) DBGFR3Init(PVM pVM);
370
371	/**
372	* Termiantes and cleans up resources allocated by the DBGF.
373	*
374	* @returns VBox status code.
375	* @param pVM VM Handle.
376	*/
377	DBGFR3DECL(int) DBGFR3Term(PVM pVM);
378
379	/**
380	* Applies relocations to data and code managed by this
381	* component. This function will be called at init and
382	* whenever the VMM need to relocate it self inside the GC.
383	*
384	* @param pVM VM handle.
385	* @param offDelta Relocation delta relative to old location.
386	*/
387	DBGFR3DECL(void) DBGFR3Relocate(PVM pVM, RTGCINTPTR offDelta);
388
389	/**
390	* Forced action callback.
391	* The VMM will call this from it's main loop when VM_FF_DBGF is set.
392	*
393	* The function checks and executes pending commands from the debugger.
394	*
395	* @returns VINF_SUCCESS normally.
396	* @returns VERR_DBGF_RAISE_FATAL_ERROR to pretend a fatal error happend.
397	* @param pVM VM Handle.
398	*/
399	DBGFR3DECL(int) DBGFR3VMMForcedAction(PVM pVM);
400
401	/**
402	* Send a generic debugger event which takes no data.
403	*
404	* @returns VBox status.
405	* @param pVM The VM handle.
406	* @param enmEvent The event to send.
407	*/
408	DBGFR3DECL(int) DBGFR3Event(PVM pVM, DBGFEVENTTYPE enmEvent);
409
410	/**
411	* Send a debugger event which takes the full source file location.
412	*
413	* @returns VBox status.
414	* @param pVM The VM handle.
415	* @param enmEvent The event to send.
416	* @param pszFile Source file.
417	* @param uLine Line number in source file.
418	* @param pszFunction Function name.
419	* @param pszFormat Message which accompanies the event.
420	* @param ... Message arguments.
421	*/
422	DBGFR3DECL(int) DBGFR3EventSrc(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszFile, unsigned uLine, const char pszFunction, const char *pszFormat, ...);
423
424	/**
425	* Send a debugger event which takes the full source file location.
426	*
427	* @returns VBox status.
428	* @param pVM The VM handle.
429	* @param enmEvent The event to send.
430	* @param pszFile Source file.
431	* @param uLine Line number in source file.
432	* @param pszFunction Function name.
433	* @param pszFormat Message which accompanies the event.
434	* @param args Message arguments.
435	*/
436	DBGFR3DECL(int) DBGFR3EventSrcV(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszFile, unsigned uLine, const char pszFunction, const char *pszFormat, va_list args);
437
438	/**
439	* Send a debugger event which takes the two assertion messages.
440	*
441	* @returns VBox status.
442	* @param pVM The VM handle.
443	* @param enmEvent The event to send.
444	* @param pszMsg1 First assertion message.
445	* @param pszMsg2 Second assertion message.
446	*/
447	DBGFR3DECL(int) DBGFR3EventAssertion(PVM pVM, DBGFEVENTTYPE enmEvent, const char pszMsg1, const char pszMsg2);
448
449	/**
450	* Breakpoint was hit somewhere.
451	* Figure out which breakpoint it is and notify the debugger.
452	*
453	* @returns VBox status.
454	* @param pVM The VM handle.
455	* @param enmEvent DBGFEVENT_BREAKPOINT_HYPER or DBGFEVENT_BREAKPOINT.
456	*/
457	DBGFR3DECL(int) DBGFR3EventBreakpoint(PVM pVM, DBGFEVENTTYPE enmEvent);
458
459	/**
460	* Attaches a debugger to the specified VM.
461	*
462	* Only one debugger at a time.
463	*
464	* @returns VBox status code.
465	* @param pVM VM Handle.
466	*/
467	DBGFR3DECL(int) DBGFR3Attach(PVM pVM);
468
469	/**
470	* Detaches a debugger from the specified VM.
471	*
472	* Caller must be attached to the VM.
473	*
474	* @returns VBox status code.
475	* @param pVM VM Handle.
476	*/
477	DBGFR3DECL(int) DBGFR3Detach(PVM pVM);
478
479	/**
480	* Wait for a debug event.
481	*
482	* @returns VBox status. Will not return VBOX_INTERRUPTED.
483	* @param pVM VM handle.
484	* @param cMillies Number of millies to wait.
485	* @param ppEvent Where to store the event pointer.
486	*/
487	DBGFR3DECL(int) DBGFR3EventWait(PVM pVM, unsigned cMillies, PCDBGFEVENT *ppEvent);
488
489	/**
490	* Halts VM execution.
491	*
492	* After calling this the VM isn't actually halted till an DBGFEVENT_HALT_DONE
493	* arrives. Until that time it's not possible to issue any new commands.
494	*
495	* @returns VBox status.
496	* @param pVM VM handle.
497	*/
498	DBGFR3DECL(int) DBGFR3Halt(PVM pVM);
499
500	/**
501	* Checks if the VM is halted by the debugger.
502	*
503	* @returns True if halted.
504	* @returns False if not halted.
505	* @param pVM VM handle.
506	*/
507	DBGFR3DECL(bool) DBGFR3IsHalted(PVM pVM);
508
509	/**
510	* Checks if the the debugger can wait for events or not.
511	*
512	* This function is only used by lazy, multiplexing debuggers. :-)
513	*
514	* @returns True if waitable.
515	* @returns False if not waitable.
516	* @param pVM VM handle.
517	*/
518	DBGFR3DECL(bool) DBGFR3CanWait(PVM pVM);
519
520	/**
521	* Resumes VM execution.
522	*
523	* There is no receipt event on this command.
524	*
525	* @returns VBox status.
526	* @param pVM VM handle.
527	*/
528	DBGFR3DECL(int) DBGFR3Resume(PVM pVM);
529
530	/**
531	* Step Into.
532	*
533	* A single step event is generated from this command.
534	* The current implementation is not reliable, so don't rely on the event comming.
535	*
536	* @returns VBox status.
537	* @param pVM VM handle.
538	*/
539	DBGFR3DECL(int) DBGFR3Step(PVM pVM);
540
541	/**
542	* Call this to single step rawmode or recompiled mode.
543	*
544	* You must pass down the return code to the EM loop! That's
545	* where the actual single stepping take place (at least in the
546	* current implementation).
547	*
548	* @returns VINF_EM_DBG_STEP
549	* @thread EMT
550	*/
551	DBGFR3DECL(int) DBGFR3PrgStep(PVM pVM);
552
553
554	/** Breakpoint type. */
555	typedef enum DBGFBPTYPE
556	{
557	/** Free breakpoint entry. */
558	DBGFBPTYPE_FREE = 0,
559	/** Debug register. */
560	DBGFBPTYPE_REG,
561	/** INT 3 instruction. */
562	DBGFBPTYPE_INT3,
563	/** Recompiler. */
564	DBGFBPTYPE_REM,
565	/** ensure 32-bit size. */
566	DBGFBPTYPE_32BIT_HACK = 0x7fffffff
567	} DBGFBPTYPE;
568
569
570	/**
571	* A Breakpoint.
572	*/
573	typedef struct DBGFBP
574	{
575	/** The number of breakpoint hits. */
576	uint64_t cHits;
577	/** The hit number which starts to trigger the breakpoint. */
578	uint64_t iHitTrigger;
579	/** The hit number which stops triggering the breakpoint (disables it).
580	* Use ~(uint64_t)0 if it should never stop. */
581	uint64_t iHitDisable;
582	/** The Flat GC address of the breakpoint.
583	* (PC register value if REM type?) */
584	RTGCUINTPTR GCPtr;
585	/** The breakpoint id. */
586	RTUINT iBp;
587	/** The breakpoint status - enabled or disabled. */
588	bool fEnabled;
589
590	/** The breakpoint type. */
591	DBGFBPTYPE enmType;
592	/** Union of type specific data. */
593	union
594	{
595	/** Debug register data. */
596	struct DBGFBPREG
597	{
598	/** The debug register number. */
599	uint8_t iReg;
600	/** The access type (one of the X86_DR7_RW_* value). */
601	uint8_t fType;
602	/** The access size. */
603	uint8_t cb;
604	} Reg;
605	/** Recompiler breakpoint data. */
606	struct DBGFBPINT3
607	{
608	/** The byte value we replaced by the INT 3 instruction. */
609	uint8_t bOrg;
610	} Int3;
611
612	/** Recompiler breakpoint data. */
613	struct DBGFBPREM
614	{
615	/** nothing yet */
616	uint8_t fDummy;
617	} Rem;
618	/** Paddind to ensure that the size is identical on win32 and linux. */
619	uint64_t u64Padding;
620	} u;
621	} DBGFBP;
622
623	/** Pointer to a breakpoint. */
624	typedef DBGFBP *PDBGFBP;
625	/** Pointer to a const breakpoint. */
626	typedef const DBGFBP *PCDBGFBP;
627
628
629	/**
630	* Sets a breakpoint (int 3 based).
631	*
632	* @returns VBox status code.
633	* @param pVM The VM handle.
634	* @param pAddress The address of the breakpoint.
635	* @param iHitTrigger The hit count at which the breakpoint start triggering.
636	* Use 0 (or 1) if it's gonna trigger at once.
637	* @param iHitDisable The hit count which disables the breakpoint.
638	* Use ~(uint64_t) if it's never gonna be disabled.
639	* @param piBp Where to store the breakpoint id. (optional)
640	* @thread Any thread.
641	*/
642	DBGFR3DECL(int) DBGFR3BpSet(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, PRTUINT piBp);
643
644	/**
645	* Sets a register breakpoint.
646	*
647	* @returns VBox status code.
648	* @param pVM The VM handle.
649	* @param pAddress The address of the breakpoint.
650	* @param iHitTrigger The hit count at which the breakpoint start triggering.
651	* Use 0 (or 1) if it's gonna trigger at once.
652	* @param iHitDisable The hit count which disables the breakpoint.
653	* Use ~(uint64_t) if it's never gonna be disabled.
654	* @param fType The access type (one of the X86_DR7_RW_* defines).
655	* @param cb The access size - 1,2,4 or 8 (the latter is AMD64 long mode only.
656	* Must be 1 if fType is X86_DR7_RW_EO.
657	* @param piBp Where to store the breakpoint id. (optional)
658	* @thread Any thread.
659	*/
660	DBGFR3DECL(int) DBGFR3BpSetReg(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable,
661	uint8_t fType, uint8_t cb, PRTUINT piBp);
662
663	/**
664	* Sets a recompiler breakpoint.
665	*
666	* @returns VBox status code.
667	* @param pVM The VM handle.
668	* @param pAddress The address of the breakpoint.
669	* @param iHitTrigger The hit count at which the breakpoint start triggering.
670	* Use 0 (or 1) if it's gonna trigger at once.
671	* @param iHitDisable The hit count which disables the breakpoint.
672	* Use ~(uint64_t) if it's never gonna be disabled.
673	* @param piBp Where to store the breakpoint id. (optional)
674	* @thread Any thread.
675	*/
676	DBGFR3DECL(int) DBGFR3BpSetREM(PVM pVM, PCDBGFADDRESS pAddress, uint64_t iHitTrigger, uint64_t iHitDisable, PRTUINT piBp);
677
678	/**
679	* Clears a breakpoint.
680	*
681	* @returns VBox status code.
682	* @param pVM The VM handle.
683	* @param iBp The id of the breakpoint which should be removed (cleared).
684	* @thread Any thread.
685	*/
686	DBGFR3DECL(int) DBGFR3BpClear(PVM pVM, RTUINT iBp);
687
688	/**
689	* Enables a breakpoint.
690	*
691	* @returns VBox status code.
692	* @param pVM The VM handle.
693	* @param iBp The id of the breakpoint which should be enabled.
694	* @thread Any thread.
695	*/
696	DBGFR3DECL(int) DBGFR3BpEnable(PVM pVM, RTUINT iBp);
697
698	/**
699	* Disables a breakpoint.
700	*
701	* @returns VBox status code.
702	* @param pVM The VM handle.
703	* @param iBp The id of the breakpoint which should be disabled.
704	* @thread Any thread.
705	*/
706	DBGFR3DECL(int) DBGFR3BpDisable(PVM pVM, RTUINT iBp);
707
708	/**
709	* Breakpoint enumeration callback function.
710	*
711	* @returns VBox status code. Any failure will stop the enumeration.
712	* @param pVM The VM handle.
713	* @param pvUser The user argument.
714	* @param pBp Pointer to the breakpoint information. (readonly)
715	*/
716	typedef DECLCALLBACK(int) FNDBGFBPENUM(PVM pVM, void *pvUser, PCDBGFBP pBp);
717	/** Pointer to a breakpoint enumeration callback function. */
718	typedef FNDBGFBPENUM *PFNDBGFBPENUM;
719
720	/**
721	* Enumerate the breakpoints.
722	*
723	* @returns VBox status code.
724	* @param pVM The VM handle.
725	* @param pfnCallback The callback function.
726	* @param pvUser The user argument to pass to the callback.
727	* @thread Any thread but the callback will be called from EMT.
728	*/
729	DBGFR3DECL(int) DBGFR3BpEnum(PVM pVM, PFNDBGFBPENUM pfnCallback, void *pvUser);
730
731
732	/**
733	* Gets the hardware breakpoint configuration as DR7.
734	*
735	* @returns DR7 from the DBGF point of view.
736	* @param pVM The VM handle.
737	*/
738	DBGFDECL(RTGCUINTREG) DBGFBpGetDR7(PVM pVM);
739
740	/**
741	* Gets the address of the hardware breakpoint number 0.
742	*
743	* @returns DR0 from the DBGF point of view.
744	* @param pVM The VM handle.
745	*/
746	DBGFDECL(RTGCUINTREG) DBGFBpGetDR0(PVM pVM);
747
748	/**
749	* Gets the address of the hardware breakpoint number 1.
750	*
751	* @returns DR1 from the DBGF point of view.
752	* @param pVM The VM handle.
753	*/
754	DBGFDECL(RTGCUINTREG) DBGFBpGetDR1(PVM pVM);
755
756	/**
757	* Gets the address of the hardware breakpoint number 2.
758	*
759	* @returns DR2 from the DBGF point of view.
760	* @param pVM The VM handle.
761	*/
762	DBGFDECL(RTGCUINTREG) DBGFBpGetDR2(PVM pVM);
763
764	/**
765	* Gets the address of the hardware breakpoint number 3.
766	*
767	* @returns DR3 from the DBGF point of view.
768	* @param pVM The VM handle.
769	*/
770	DBGFDECL(RTGCUINTREG) DBGFBpGetDR3(PVM pVM);
771
772	/**
773	* Returns single stepping state
774	*
775	* @returns stepping or not
776	* @param pVM The VM handle.
777	*/
778	DBGFDECL(bool) DBGFIsStepping(PVM pVM);
779
780
781	/** Pointer to a info helper callback structure. */
782	typedef struct DBGFINFOHLP *PDBGFINFOHLP;
783	/** Pointer to a const info helper callback structure. */
784	typedef const struct DBGFINFOHLP *PCDBGFINFOHLP;
785
786	/**
787	* Info helper callback structure.
788	*/
789	typedef struct DBGFINFOHLP
790	{
791	/**
792	* Print formatted string.
793	*
794	* @param pHlp Pointer to this structure.
795	* @param pszFormat The format string.
796	* @param ... Arguments.
797	*/
798	DECLCALLBACKMEMBER(void, pfnPrintf)(PCDBGFINFOHLP pHlp, const char *pszFormat, ...);
799
800	/**
801	* Print formatted string.
802	*
803	* @param pHlp Pointer to this structure.
804	* @param pszFormat The format string.
805	* @param args Argument list.
806	*/
807	DECLCALLBACKMEMBER(void, pfnPrintfV)(PCDBGFINFOHLP pHlp, const char *pszFormat, va_list args);
808	} DBGFINFOHLP;
809
810
811	/**
812	* Info handler, device version.
813	*
814	* @param pDevIns Device instance which registered the info.
815	* @param pHlp Callback functions for doing output.
816	* @param pszArgs Argument string. Optional and specific to the handler.
817	*/
818	typedef DECLCALLBACK(void) FNDBGFHANDLERDEV(PPDMDEVINS pDevIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
819	/** Pointer to a FNDBGFHANDLERDEV function. */
820	typedef FNDBGFHANDLERDEV *PFNDBGFHANDLERDEV;
821
822	/**
823	* Info handler, driver version.
824	*
825	* @param pDrvIns Driver instance which registered the info.
826	* @param pHlp Callback functions for doing output.
827	* @param pszArgs Argument string. Optional and specific to the handler.
828	*/
829	typedef DECLCALLBACK(void) FNDBGFHANDLERDRV(PPDMDRVINS pDrvIns, PCDBGFINFOHLP pHlp, const char *pszArgs);
830	/** Pointer to a FNDBGFHANDLERDRV function. */
831	typedef FNDBGFHANDLERDRV *PFNDBGFHANDLERDRV;
832
833	/**
834	* Info handler, internal version.
835	*
836	* @param pVM The VM handle.
837	* @param pHlp Callback functions for doing output.
838	* @param pszArgs Argument string. Optional and specific to the handler.
839	*/
840	typedef DECLCALLBACK(void) FNDBGFHANDLERINT(PVM pVM, PCDBGFINFOHLP pHlp, const char *pszArgs);
841	/** Pointer to a FNDBGFHANDLERINT function. */
842	typedef FNDBGFHANDLERINT *PFNDBGFHANDLERINT;
843
844	/**
845	* Info handler, external version.
846	*
847	* @param pvUser User argument.
848	* @param pHlp Callback functions for doing output.
849	* @param pszArgs Argument string. Optional and specific to the handler.
850	*/
851	typedef DECLCALLBACK(void) FNDBGFHANDLEREXT(void pvUser, PCDBGFINFOHLP pHlp, const char pszArgs);
852	/** Pointer to a FNDBGFHANDLEREXT function. */
853	typedef FNDBGFHANDLEREXT *PFNDBGFHANDLEREXT;
854
855
856	/** @name Flags for the info registration functions.
857	* @{ */
858	/** The handler must run on the EMT. */
859	#define DBGFINFO_FLAGS_RUN_ON_EMT RT_BIT(0)
860	/** @} */
861
862
863	/**
864	* Register a info handler owned by a device.
865	*
866	* @returns VBox status code.
867	* @param pVM VM handle.
868	* @param pszName The identifier of the info.
869	* @param pszDesc The description of the info and any arguments the handler may take.
870	* @param pfnHandler The handler function to be called to display the info.
871	* @param pDevIns The device instance owning the info.
872	*/
873	DBGFR3DECL(int) DBGFR3InfoRegisterDevice(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERDEV pfnHandler, PPDMDEVINS pDevIns);
874
875	/**
876	* Register a info handler owned by a driver.
877	*
878	* @returns VBox status code.
879	* @param pVM VM handle.
880	* @param pszName The identifier of the info.
881	* @param pszDesc The description of the info and any arguments the handler may take.
882	* @param pfnHandler The handler function to be called to display the info.
883	* @param pDrvIns The driver instance owning the info.
884	*/
885	DBGFR3DECL(int) DBGFR3InfoRegisterDriver(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERDRV pfnHandler, PPDMDRVINS pDrvIns);
886
887	/**
888	* Register a info handler owned by an internal component.
889	*
890	* @returns VBox status code.
891	* @param pVM VM handle.
892	* @param pszName The identifier of the info.
893	* @param pszDesc The description of the info and any arguments the handler may take.
894	* @param pfnHandler The handler function to be called to display the info.
895	*/
896	DBGFR3DECL(int) DBGFR3InfoRegisterInternal(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERINT pfnHandler);
897
898	/**
899	* Register a info handler owned by an internal component.
900	*
901	* @returns VBox status code.
902	* @param pVM VM handle.
903	* @param pszName The identifier of the info.
904	* @param pszDesc The description of the info and any arguments the handler may take.
905	* @param pfnHandler The handler function to be called to display the info.
906	* @param fFlags Flags, see the DBGFINFO_FLAGS_*.
907	*/
908	DBGFR3DECL(int) DBGFR3InfoRegisterInternalEx(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLERINT pfnHandler, uint32_t fFlags);
909
910	/**
911	* Register a info handler owned by an external component.
912	*
913	* @returns VBox status code.
914	* @param pVM VM handle.
915	* @param pszName The identifier of the info.
916	* @param pszDesc The description of the info and any arguments the handler may take.
917	* @param pfnHandler The handler function to be called to display the info.
918	* @param pvUser User argument to be passed to the handler.
919	*/
920	DBGFR3DECL(int) DBGFR3InfoRegisterExternal(PVM pVM, const char pszName, const char pszDesc, PFNDBGFHANDLEREXT pfnHandler, void *pvUser);
921
922	/**
923	* Deregister one(/all) info handler(s) owned by a device.
924	*
925	* @returns VBox status code.
926	* @param pVM VM Handle.
927	* @param pDevIns Device instance.
928	* @param pszName The identifier of the info. If NULL all owned by the device.
929	*/
930	DBGFR3DECL(int) DBGFR3InfoDeregisterDevice(PVM pVM, PPDMDEVINS pDevIns, const char *pszName);
931
932	/**
933	* Deregister one(/all) info handler(s) owned by a driver.
934	*
935	* @returns VBox status code.
936	* @param pVM VM Handle.
937	* @param pDrvIns Driver instance.
938	* @param pszName The identifier of the info. If NULL all owned by the driver.
939	*/
940	DBGFR3DECL(int) DBGFR3InfoDeregisterDriver(PVM pVM, PPDMDRVINS pDrvIns, const char *pszName);
941
942	/**
943	* Deregister a info handler owned by an internal component.
944	*
945	* @returns VBox status code.
946	* @param pVM VM Handle.
947	* @param pszName The identifier of the info. If NULL all owned by the device.
948	*/
949	DBGFR3DECL(int) DBGFR3InfoDeregisterInternal(PVM pVM, const char *pszName);
950
951	/**
952	* Deregister a info handler owned by an external component.
953	*
954	* @returns VBox status code.
955	* @param pVM VM Handle.
956	* @param pszName The identifier of the info. If NULL all owned by the device.
957	*/
958	DBGFR3DECL(int) DBGFR3InfoDeregisterExternal(PVM pVM, const char *pszName);
959
960	/**
961	* Display a piece of info writing to the supplied handler.
962	*
963	* @returns VBox status code.
964	* @param pVM VM handle.
965	* @param pszName The identifier of the info to display.
966	* @param pszArgs Arguments to the info handler.
967	* @param pHlp The output helper functions. If NULL the logger will be used.
968	*/
969	DBGFR3DECL(int) DBGFR3Info(PVM pVM, const char pszName, const char pszArgs, PCDBGFINFOHLP pHlp);
970
971	/** @def DBGFR3InfoLog
972	* Display a piece of info writing to the log if enabled.
973	*
974	* @param pVM VM handle.
975	* @param pszName The identifier of the info to display.
976	* @param pszArgs Arguments to the info handler.
977	*/
978	#ifdef LOG_ENABLED
979	#define DBGFR3InfoLog(pVM, pszName, pszArgs) \
980	do { \
981	if (LogIsEnabled()) \
982	DBGFR3Info(pVM, pszName, pszArgs, NULL); \
983	} while (0)
984	#else
985	#define DBGFR3InfoLog(pVM, pszName, pszArgs) do { } while (0)
986	#endif
987
988
989	/**
990	* Changes the logger group settings.
991	*
992	* @returns VBox status code.
993	* @param pVM The VM handle.
994	* @param pszGroupSettings The group settings string. (VBOX_LOG)
995	*/
996	DBGFR3DECL(int) DBGFR3LogModifyGroups(PVM pVM, const char *pszGroupSettings);
997
998	/**
999	* Changes the logger flag settings.
1000	*
1001	* @returns VBox status code.
1002	* @param pVM The VM handle.
1003	* @param pszFlagSettings The flag settings string. (VBOX_LOG_FLAGS)
1004	*/
1005	DBGFR3DECL(int) DBGFR3LogModifyFlags(PVM pVM, const char *pszFlagSettings);
1006
1007	/**
1008	* Changes the logger destination settings.
1009	*
1010	* @returns VBox status code.
1011	* @param pVM The VM handle.
1012	* @param pszDestSettings The destination settings string. (VBOX_LOG_DEST)
1013	*/
1014	DBGFR3DECL(int) DBGFR3LogModifyDestinations(PVM pVM, const char *pszDestSettings);
1015
1016
1017	/**
1018	* Enumeration callback for use with DBGFR3InfoEnum.
1019	*
1020	* @returns VBox status code.
1021	* A status code indicating failure will end the enumeration
1022	* and DBGFR3InfoEnum will return with that status code.
1023	* @param pVM VM handle.
1024	* @param pszName Info identifier name.
1025	* @param pszDesc The description.
1026	*/
1027	typedef DECLCALLBACK(int) FNDBGFINFOENUM(PVM pVM, const char pszName, const char pszDesc, void *pvUser);
1028	/** Pointer to a FNDBGFINFOENUM function. */
1029	typedef FNDBGFINFOENUM *PFNDBGFINFOENUM;
1030
1031	/**
1032	* Enumerate all the register info handlers.
1033	*
1034	* @returns VBox status code.
1035	* @param pVM VM handle.
1036	* @param pfnCallback Pointer to callback function.
1037	* @param pvUser User argument to pass to the callback.
1038	*/
1039	DBGFR3DECL(int) DBGFR3InfoEnum(PVM pVM, PFNDBGFINFOENUM pfnCallback, void *pvUser);
1040
1041	/**
1042	* Gets the logger info helper.
1043	* The returned info helper will unconditionally write all output to the log.
1044	*
1045	* @returns Pointer to the logger info helper.
1046	*/
1047	DBGFR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogHlp(void);
1048
1049	/**
1050	* Gets the release logger info helper.
1051	* The returned info helper will unconditionally write all output to the release log.
1052	*
1053	* @returns Pointer to the release logger info helper.
1054	*/
1055	DBGFR3DECL(PCDBGFINFOHLP) DBGFR3InfoLogRelHlp(void);
1056
1057
1058
1059	/** Max length (including '\\0') of a symbol name. */
1060	#define DBGF_SYMBOL_NAME_LENGTH 512
1061
1062	/**
1063	* Debug symbol.
1064	*/
1065	typedef struct DBGFSYMBOL
1066	{
1067	/** Symbol value (address). */
1068	RTGCUINTPTR Value;
1069	/** Symbol size. */
1070	uint32_t cb;
1071	/** Symbol Flags. (reserved). */
1072	uint32_t fFlags;
1073	/** Symbol name. */
1074	char szName[DBGF_SYMBOL_NAME_LENGTH];
1075	} DBGFSYMBOL;
1076	/** Pointer to debug symbol. */
1077	typedef DBGFSYMBOL *PDBGFSYMBOL;
1078	/** Pointer to const debug symbol. */
1079	typedef const DBGFSYMBOL *PCDBGFSYMBOL;
1080
1081	/**
1082	* Debug line number information.
1083	*/
1084	typedef struct DBGFLINE
1085	{
1086	/** Address. */
1087	RTGCUINTPTR Address;
1088	/** Line number. */
1089	uint32_t uLineNo;
1090	/** Filename. */
1091	char szFilename[260];
1092	} DBGFLINE;
1093	/** Pointer to debug line number. */
1094	typedef DBGFLINE *PDBGFLINE;
1095	/** Pointer to const debug line number. */
1096	typedef const DBGFLINE *PCDBGFLINE;
1097
1098
1099	/**
1100	* Load debug info, optionally related to a specific module.
1101	*
1102	* @returns VBox status.
1103	* @param pVM VM Handle.
1104	* @param pszFilename Path to the file containing the symbol information.
1105	* This can be the executable image, a flat symbol file of some kind or stripped debug info.
1106	* @param AddressDelta The value to add to the loaded symbols.
1107	* @param pszName Short hand name for the module. If not related to a module specify NULL.
1108	* @param Address Address which the image is loaded at. This will be used to reference the module other places in the api.
1109	* Ignored when pszName is NULL.
1110	* @param cbImage Size of the image.
1111	* Ignored when pszName is NULL.
1112	*/
1113	DBGFR3DECL(int) DBGFR3ModuleLoad(PVM pVM, const char pszFilename, RTGCUINTPTR AddressDelta, const char pszName, RTGCUINTPTR ModuleAddress, unsigned cbImage);
1114
1115	/**
1116	* Interface used by PDMR3LdrRelocate for telling us that a GC module has been relocated.
1117	*
1118	* @param pVM The VM handle.
1119	* @param OldImageBase The old image base.
1120	* @param NewImageBase The new image base.
1121	* @param cbImage The image size.
1122	* @param pszFilename The image filename.
1123	* @param pszName The module name.
1124	*/
1125	DBGFR3DECL(void) DBGFR3ModuleRelocate(PVM pVM, RTGCUINTPTR OldImageBase, RTGCUINTPTR NewImageBase, unsigned cbImage,
1126	const char pszFilename, const char pszName);
1127
1128	/**
1129	* Adds a symbol to the debug info manager.
1130	*
1131	* @returns VBox status.
1132	* @param pVM VM Handle.
1133	* @param ModuleAddress Module address. Use 0 if no module.
1134	* @param SymbolAddress Symbol address
1135	* @param cbSymbol Size of the symbol. Use 0 if info not available.
1136	* @param pszSymbol Symbol name.
1137	*/
1138	DBGFR3DECL(int) DBGFR3SymbolAdd(PVM pVM, RTGCUINTPTR ModuleAddress, RTGCUINTPTR SymbolAddress, RTUINT cbSymbol, const char *pszSymbol);
1139
1140	/**
1141	* Find symbol by address (nearest).
1142	*
1143	* @returns VBox status.
1144	* @param pVM VM handle.
1145	* @param Address Address.
1146	* @param poffDisplacement Where to store the symbol displacement from Address.
1147	* @param pSymbol Where to store the symbol info.
1148	*/
1149	DBGFR3DECL(int) DBGFR3SymbolByAddr(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement, PDBGFSYMBOL pSymbol);
1150
1151	/**
1152	* Find symbol by name (first).
1153	*
1154	* @returns VBox status.
1155	* @param pVM VM handle.
1156	* @param pszSymbol Symbol name.
1157	* @param pSymbol Where to store the symbol info.
1158	*/
1159	DBGFR3DECL(int) DBGFR3SymbolByName(PVM pVM, const char *pszSymbol, PDBGFSYMBOL pSymbol);
1160
1161	/**
1162	* Find symbol by address (nearest), allocate return buffer.
1163	*
1164	* @returns Pointer to the symbol. Must be freed using DBGFR3SymbolFree().
1165	* @returns NULL if the symbol was not found or if we're out of memory.
1166	* @param pVM VM handle.
1167	* @param Address Address.
1168	* @param poffDisplacement Where to store the symbol displacement from Address.
1169	*/
1170	DBGFR3DECL(PDBGFSYMBOL) DBGFR3SymbolByAddrAlloc(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement);
1171
1172	/**
1173	* Find symbol by name (first), allocate return buffer.
1174	*
1175	* @returns Pointer to the symbol. Must be freed using DBGFR3SymbolFree().
1176	* @returns NULL if the symbol was not found or if we're out of memory.
1177	* @param pVM VM handle.
1178	* @param pszSymbol Symbol name.
1179	* @param ppSymbol Where to store the pointer to the symbol info.
1180	*/
1181	DBGFR3DECL(PDBGFSYMBOL) DBGFR3SymbolByNameAlloc(PVM pVM, const char *pszSymbol);
1182
1183	/**
1184	* Frees a symbol returned by DBGFR3SymbolbyNameAlloc() or DBGFR3SymbolByAddressAlloc().
1185	*
1186	* @param pSymbol Pointer to the symbol.
1187	*/
1188	DBGFR3DECL(void) DBGFR3SymbolFree(PDBGFSYMBOL pSymbol);
1189
1190	/**
1191	* Find line by address (nearest).
1192	*
1193	* @returns VBox status.
1194	* @param pVM VM handle.
1195	* @param Address Address.
1196	* @param poffDisplacement Where to store the line displacement from Address.
1197	* @param pLine Where to store the line info.
1198	*/
1199	DBGFR3DECL(int) DBGFR3LineByAddr(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement, PDBGFLINE pLine);
1200
1201	/**
1202	* Find line by address (nearest), allocate return buffer.
1203	*
1204	* @returns Pointer to the line. Must be freed using DBGFR3LineFree().
1205	* @returns NULL if the line was not found or if we're out of memory.
1206	* @param pVM VM handle.
1207	* @param Address Address.
1208	* @param poffDisplacement Where to store the line displacement from Address.
1209	*/
1210	DBGFR3DECL(PDBGFLINE) DBGFR3LineByAddrAlloc(PVM pVM, RTGCUINTPTR Address, PRTGCINTPTR poffDisplacement);
1211
1212	/**
1213	* Frees a line returned by DBGFR3LineByAddressAlloc().
1214	*
1215	* @param pLine Pointer to the line.
1216	*/
1217	DBGFR3DECL(void) DBGFR3LineFree(PDBGFLINE pLine);
1218
1219	/**
1220	* Return type.
1221	*/
1222	typedef enum DBGFRETRUNTYPE
1223	{
1224	/** The usual invalid 0 value. */
1225	DBGFRETURNTYPE_INVALID = 0,
1226	/** Near 16-bit return. */
1227	DBGFRETURNTYPE_NEAR16,
1228	/** Near 32-bit return. */
1229	DBGFRETURNTYPE_NEAR32,
1230	/** Near 64-bit return. */
1231	DBGFRETURNTYPE_NEAR64,
1232	/** Far 16:16 return. */
1233	DBGFRETURNTYPE_FAR16,
1234	/** Far 16:32 return. */
1235	DBGFRETURNTYPE_FAR32,
1236	/** Far 16:64 return. */
1237	DBGFRETURNTYPE_FAR64,
1238	/** 16-bit iret return (e.g. real or 286 protect mode). */
1239	DBGFRETURNTYPE_IRET16,
1240	/** 32-bit iret return. */
1241	DBGFRETURNTYPE_IRET32,
1242	/** 32-bit iret return. */
1243	DBGFRETURNTYPE_IRET32_PRIV,
1244	/** 32-bit iret return to V86 mode. */
1245	DBGFRETURNTYPE_IRET32_V86,
1246	/** @todo 64-bit iret return. */
1247	DBGFRETURNTYPE_IRET64,
1248	/** The usual 32-bit blowup. */
1249	DBGFRETURNTYPE_32BIT_HACK = 0x7fffffff
1250	} DBGFRETURNTYPE;
1251
1252
1253	/**
1254	* Figures the size of the return state on the stack.
1255	*
1256	* @returns number of bytes. 0 if invalid parameter.
1257	* @param enmRetType The type of return.
1258	*/
1259	DECLINLINE(unsigned) DBGFReturnTypeSize(DBGFRETURNTYPE enmRetType)
1260	{
1261	switch (enmRetType)
1262	{
1263	case DBGFRETURNTYPE_NEAR16: return 2;
1264	case DBGFRETURNTYPE_NEAR32: return 4;
1265	case DBGFRETURNTYPE_NEAR64: return 8;
1266	case DBGFRETURNTYPE_FAR16: return 4;
1267	case DBGFRETURNTYPE_FAR32: return 4;
1268	case DBGFRETURNTYPE_FAR64: return 8;
1269	case DBGFRETURNTYPE_IRET16: return 6;
1270	case DBGFRETURNTYPE_IRET32: return 4*3;
1271	case DBGFRETURNTYPE_IRET32_PRIV: return 4*5;
1272	case DBGFRETURNTYPE_IRET32_V86: return 4*9;
1273	case DBGFRETURNTYPE_IRET64:
1274	default:
1275	return 0;
1276	}
1277	}
1278
1279
1280	/** Pointer to stack frame info. */
1281	typedef struct DBGFSTACKFRAME *PDBGFSTACKFRAME;
1282	/**
1283	* Info about a stack frame.
1284	*/
1285	typedef struct DBGFSTACKFRAME
1286	{
1287	/** Frame number. */
1288	RTUINT iFrame;
1289	/** Frame flags. */
1290	RTUINT fFlags;
1291	/** The frame address.
1292	* The off member is [e\|r]bp and the Sel member is ss. */
1293	DBGFADDRESS AddrFrame;
1294	/** The stack address of the frame.
1295	* The off member is [e\|r]sp and the Sel member is ss. */
1296	DBGFADDRESS AddrStack;
1297	/** The program counter (PC) address of the frame.
1298	* The off member is [e\|r]ip and the Sel member is cs. */
1299	DBGFADDRESS AddrPC;
1300	/** Pointer to the symbol nearest the program counter (PC). NULL if not found. */
1301	PDBGFSYMBOL pSymPC;
1302	/** Pointer to the linnumber nearest the program counter (PC). NULL if not found. */
1303	PDBGFLINE pLinePC;
1304
1305	/** The return frame address.
1306	* The off member is [e\|r]bp and the Sel member is ss. */
1307	DBGFADDRESS AddrReturnFrame;
1308	/** The return stack address.
1309	* The off member is [e\|r]sp and the Sel member is ss. */
1310	DBGFADDRESS AddrReturnStack;
1311	/** The way this frame returns to the next one. */
1312	DBGFRETURNTYPE enmReturnType;
1313
1314	/** The program counter (PC) address which the frame returns to.
1315	* The off member is [e\|r]ip and the Sel member is cs. */
1316	DBGFADDRESS AddrReturnPC;
1317	/** Pointer to the symbol nearest the return PC. NULL if not found. */
1318	PDBGFSYMBOL pSymReturnPC;
1319	/** Pointer to the linnumber nearest the return PC. NULL if not found. */
1320	PDBGFLINE pLineReturnPC;
1321
1322	/** 32-bytes of stack arguments. */
1323	union
1324	{
1325	/** 64-bit view */
1326	uint64_t au64[4];
1327	/** 32-bit view */
1328	uint32_t au32[8];
1329	/** 16-bit view */
1330	uint16_t au16[16];
1331	/** 8-bit view */
1332	uint8_t au8[32];
1333	} Args;
1334
1335	/** Pointer to the next frame.
1336	* Might not be used in some cases, so consider it internal. */
1337	PDBGFSTACKFRAME pNext;
1338	/** Pointer to the first frame.
1339	* Might not be used in some cases, so consider it internal. */
1340	PDBGFSTACKFRAME pFirst;
1341	} DBGFSTACKFRAME;
1342
1343	/** @name DBGFSTACKFRAME Flags.
1344	* @{ */
1345	/** Set if the content of the frame is filled in by DBGFR3StackWalk() and can be used
1346	* to construct the next frame. */
1347	#define DBGFSTACKFRAME_FLAGS_ALL_VALID RT_BIT(0)
1348	/** This is the last stack frame we can read.
1349	* This flag is not set if the walk stop because of max dept or recursion. */
1350	#define DBGFSTACKFRAME_FLAGS_LAST RT_BIT(1)
1351	/** This is the last record because we detected a loop. */
1352	#define DBGFSTACKFRAME_FLAGS_LOOP RT_BIT(2)
1353	/** This is the last record because we reached the maximum depth. */
1354	#define DBGFSTACKFRAME_FLAGS_MAX_DEPTH RT_BIT(3)
1355	/** @} */
1356
1357	/**
1358	* Begins a stack walk.
1359	* This will construct and obtain the first frame.
1360	*
1361	* @returns VINF_SUCCESS on success.
1362	* @returns VERR_NO_MEMORY if we're out of memory.
1363	* @param pVM The VM handle.
1364	* @param pFrame The stack frame info structure.
1365	* On input this structure must be memset to zero.
1366	* If wanted, the AddrPC, AddrStack and AddrFrame fields may be set
1367	* to valid addresses after memsetting it. Any of those fields not set
1368	* will be fetched from the guest CPU state.
1369	* On output the structure will contain all the information we were able to
1370	* obtain about the stack frame.
1371	*/
1372	DBGFR3DECL(int) DBGFR3StackWalkBeginGuest(PVM pVM, PDBGFSTACKFRAME pFrame);
1373
1374	/**
1375	* Begins a stack walk.
1376	* This will construct and obtain the first frame.
1377	*
1378	* @returns VINF_SUCCESS on success.
1379	* @returns VERR_NO_MEMORY if we're out of memory.
1380	* @param pVM The VM handle.
1381	* @param pFrame The stack frame info structure.
1382	* On input this structure must be memset to zero.
1383	* If wanted, the AddrPC, AddrStack and AddrFrame fields may be set
1384	* to valid addresses after memsetting it. Any of those fields not set
1385	* will be fetched from the hypervisor CPU state.
1386	* On output the structure will contain all the information we were able to
1387	* obtain about the stack frame.
1388	*/
1389	DBGFR3DECL(int) DBGFR3StackWalkBeginHyper(PVM pVM, PDBGFSTACKFRAME pFrame);
1390
1391	/**
1392	* Gets the next stack frame.
1393	*
1394	* @returns VINF_SUCCESS
1395	* @returns VERR_NO_MORE_FILES if not more stack frames.
1396	* @param pVM The VM handle.
1397	* @param pFrame Pointer to the current frame on input, content is replaced with the next frame on successful return.
1398	*/
1399	DBGFR3DECL(int) DBGFR3StackWalkNext(PVM pVM, PDBGFSTACKFRAME pFrame);
1400
1401	/**
1402	* Ends a stack walk process.
1403	*
1404	* This must be called after a successful first call to any of the stack
1405	* walker functions. If not called we will leak memory or other resources.
1406	*
1407	* @param pVM The VM handle.
1408	* @param pFrame The stackframe as returned by the last stack walk call.
1409	*/
1410	DBGFR3DECL(void) DBGFR3StackWalkEnd(PVM pVM, PDBGFSTACKFRAME pFrame);
1411
1412
1413
1414
1415	/** Flags to pass to DBGFR3DisasInstrEx().
1416	* @{ */
1417	/** Disassemble the current guest instruction, with annotations. */
1418	#define DBGF_DISAS_FLAGS_CURRENT_GUEST RT_BIT(0)
1419	/** Disassemble the current hypervisor instruction, with annotations. */
1420	#define DBGF_DISAS_FLAGS_CURRENT_HYPER RT_BIT(1)
1421	/** No annotations for current context. */
1422	#define DBGF_DISAS_FLAGS_NO_ANNOTATION RT_BIT(2)
1423	/** No symbol lookup. */
1424	#define DBGF_DISAS_FLAGS_NO_SYMBOLS RT_BIT(3)
1425	/** No instruction bytes. */
1426	#define DBGF_DISAS_FLAGS_NO_BYTES RT_BIT(4)
1427	/** No address in the output. */
1428	#define DBGF_DISAS_FLAGS_NO_ADDRESS RT_BIT(5)
1429	/** @} */
1430
1431	/** Special flat selector. */
1432	#define DBGF_SEL_FLAT 1
1433
1434	/**
1435	* Disassembles the one instruction according to the specified flags and address.
1436	*
1437	* @returns VBox status code.
1438	* @param pVM VM handle.
1439	* @param Sel The code selector. This used to determin the 32/16 bit ness and
1440	* calculation of the actual instruction address.
1441	* Use DBGF_SEL_FLAT for specifying a flat address.
1442	* @param GCPtr The code address relative to the base of Sel.
1443	* @param fFlags Flags controlling where to start and how to format.
1444	* A combination of the DBGF_DISAS_FLAGS_* #defines.
1445	* @param pszOutput Output buffer.
1446	* @param cchOutput Size of the output buffer.
1447	* @param pcbInstr Where to return the size of the instruction.
1448	*/
1449	DBGFR3DECL(int) DBGFR3DisasInstrEx(PVM pVM, RTSEL Sel, RTGCPTR GCPtr, unsigned fFlags, char pszOutput, uint32_t cchOutput, uint32_t pcbInstr);
1450
1451	/**
1452	* Disassembles the current instruction.
1453	* Addresses will be tried resolved to symbols
1454	*
1455	* @returns VBox status code.
1456	* @param pVM VM handle.
1457	* @param Sel The code selector. This used to determin the 32/16 bit ness and
1458	* calculation of the actual instruction address.
1459	* Use DBGF_SEL_FLAT for specifying a flat address.
1460	* @param GCPtr The code address relative to the base of Sel.
1461	* @param pszOutput Output buffer.
1462	* @param cbOutput Size of the output buffer.
1463	*/
1464	DBGFR3DECL(int) DBGFR3DisasInstr(PVM pVM, RTSEL Sel, RTGCPTR GCPtr, char *pszOutput, uint32_t cbOutput);
1465
1466	/**
1467	* Disassembles the current instruction.
1468	* All registers and data will be displayed. Addresses will be attempted resolved to symbols
1469	*
1470	* @returns VBox status code.
1471	* @param pVM VM handle.
1472	* @param pszOutput Output buffer.
1473	* @param cbOutput Size of the output buffer.
1474	*/
1475	DBGFR3DECL(int) DBGFR3DisasInstrCurrent(PVM pVM, char *pszOutput, uint32_t cbOutput);
1476
1477	/**
1478	* Disassembles the current guest context instruction and writes it to the log.
1479	* All registers and data will be displayed. Addresses will be attempted resolved to symbols.
1480	*
1481	* @returns VBox status code.
1482	* @param pVM VM handle.
1483	* @param pszPrefix Short prefix string to the dissassembly string. (optional)
1484	*/
1485	DBGFR3DECL(int) DBGFR3DisasInstrCurrentLogInternal(PVM pVM, const char *pszPrefix);
1486
1487	/** @def DBGFR3DisasInstrCurrentLog
1488	* Disassembles the current guest context instruction and writes it to the log.
1489	* All registers and data will be displayed. Addresses will be attempted resolved to symbols.
1490	*/
1491	#ifdef LOG_ENABLED
1492	# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) \
1493	do { \
1494	if (LogIsEnabled()) \
1495	DBGFR3DisasInstrCurrentLogInternal(pVM, pszPrefix); \
1496	} while (0)
1497	#else
1498	# define DBGFR3DisasInstrCurrentLog(pVM, pszPrefix) do { } while (0)
1499	#endif
1500
1501	/**
1502	* Disassembles the specified guest context instruction and writes it to the log.
1503	* Addresses will be attempted resolved to symbols.
1504	*
1505	* @returns VBox status code.
1506	* @param pVM VM handle.
1507	* @param Sel The code selector. This used to determin the 32/16 bit-ness and
1508	* calculation of the actual instruction address.
1509	* @param GCPtr The code address relative to the base of Sel.
1510	*/
1511	DBGFR3DECL(int) DBGFR3DisasInstrLogInternal(PVM pVM, RTSEL Sel, RTGCPTR GCPtr);
1512
1513	/** @def DBGFR3DisasInstrLog
1514	* Disassembles the specified guest context instruction and writes it to the log.
1515	* Addresses will be attempted resolved to symbols.
1516	*/
1517	#ifdef LOG_ENABLED
1518	# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) \
1519	do { \
1520	if (LogIsEnabled()) \
1521	DBGFR3DisasInstrLogInternal(pVM, Sel, GCPtr); \
1522	} while (0)
1523	#else
1524	# define DBGFR3DisasInstrLog(pVM, Sel, GCPtr) do { } while (0)
1525	#endif
1526
1527
1528	/**
1529	* Scan guest memory for an exact byte string.
1530	*
1531	* @returns VBox status codes:
1532	* @retval VINF_SUCCESS and *pGCPtrHit on success.
1533	* @retval VERR_DBGF_MEM_NOT_FOUND if not found.
1534	* @retval VERR_INVALID_POINTER if any of the pointer arguments are invalid.
1535	* @retval VERR_INVALID_ARGUMENT if any other arguments are invalid.
1536	*
1537	* @param pVM The VM handle.
1538	* @param pAddress Where to store the mixed address.
1539	* @param cbRange The number of bytes to scan.
1540	* @param pabNeedle What to search for - exact search.
1541	* @param cbNeedle Size of the search byte string.
1542	* @param pHitAddress Where to put the address of the first hit.
1543	*
1544	* @thread Any thread.
1545	*/
1546	DBGFR3DECL(int) DBGFR3MemScan(PVM pVM, PCDBGFADDRESS pAddress, RTGCUINTPTR cbRange, const uint8_t *pabNeedle, size_t cbNeedle, PDBGFADDRESS pHitAddress);
1547
1548	/** @} */
1549
1550	__END_DECLS
1551
1552	#endif

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

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

Download in other formats: