dbgfflowtrace.h@ 87518

Last change on this file since 87518 was 87140, checked in by vboxsync, 4 years ago
VMM/DBGFR3FlowTrace: First commit of a new DBGF framework to collect guest state information during execution, allowing visualization of guest execution flow, bugref:8650 [scm]
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.2 KB

Line
1	/** @file
2	* DBGF - Debugger Facility, Guest execution flow tracing.
3	*/
4
5	/*
6	* Copyright (C) 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_dbgfflowtrace_h
27	#define VBOX_INCLUDED_vmm_dbgfflowtrace_h
28	#ifndef RT_WITHOUT_PRAGMA_ONCE
29	# pragma once
30	#endif
31
32	#include <VBox/types.h>
33	#include <VBox/vmm/dbgf.h>
34
35	RT_C_DECLS_BEGIN
36	/** @defgroup grp_dbgf_flowtrace Guest Execution Flow Tracing
37	* @ingroup grp_dbgf
38	*
39	* @{
40	*/
41
42	/** A DBGF flow trace module handle. */
43	typedef struct DBGFFLOWTRACEMODINT *DBGFFLOWTRACEMOD;
44	/** Pointer to a DBGF flow trace module handle. */
45	typedef DBGFFLOWTRACEMOD *PDBGFFLOWTRACEMOD;
46	/** A DBGF flow trace probe handle. */
47	typedef struct DBGFFLOWTRACEPROBEINT *DBGFFLOWTRACEPROBE;
48	/** Pointer to a DBGF flow trace state probe handle. */
49	typedef DBGFFLOWTRACEPROBE *PDBGFFLOWTRACEPROBE;
50	/** A DBGF flow trace report handle. */
51	typedef struct DBGFFLOWTRACEREPORTINT *DBGFFLOWTRACEREPORT;
52	/** Pointer to a DBGF flow trace report handle. */
53	typedef DBGFFLOWTRACEREPORT *PDBGFFLOWTRACEREPORT;
54	/** A DBGF flow trace record handle. */
55	typedef struct DBGFFLOWTRACERECORDINT *DBGFFLOWTRACERECORD;
56	/** Pointer to a DBGF flow trace record handle. */
57	typedef DBGFFLOWTRACERECORD *PDBGFFLOWTRACERECORD;
58
59
60	/** Pointer to a flow trace probe entry. */
61	typedef struct DBGFFLOWTRACEPROBEENTRY *PDBGFFLOWTRACEPROBEENTRY;
62	/** Pointer to a const flow trace probe entry. */
63	typedef const struct DBGFFLOWTRACEPROBEENTRY *PCDBGFFLOWTRACEPROBEENTRY;
64
65	/** @name Flags controlling the type of the addition of a single probe.
66	* @{ */
67	/** Default options. */
68	#define DBGF_FLOW_TRACE_PROBE_ADD_F_DEFAULT DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC
69	/** Collects the data specified by the data probe before the instruction is executed. */
70	#define DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC RT_BIT_32(0)
71	/** Collects the data specified by the data probe after the instruction was executed. */
72	#define DBGF_FLOW_TRACE_PROBE_ADD_F_AFTER_EXEC RT_BIT_32(1)
73	/** Mask of all valid flags. */
74	#define DBGF_FLOW_TRACE_PROBE_ADD_F_VALID_MASK ( DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC \
75	\| DBGF_FLOW_TRACE_PROBE_ADD_F_AFTER_EXEC)
76	/** @} */
77
78
79	/**
80	* Probe entry type.
81	*/
82	typedef enum DBGFFLOWTRACEPROBEENTRYTYPE
83	{
84	/** Invalid type. */
85	DBGFFLOWTRACEPROBEENTRYTYPE_INVALID = 0,
86	/** Register. */
87	DBGFFLOWTRACEPROBEENTRYTYPE_REG,
88	/** Constant memory buffer pointer. */
89	DBGFFLOWTRACEPROBEENTRYTYPE_CONST_MEM,
90	/** Indirect memory buffer pointer, obtained from the base and index register
91	* and a constant scale. */
92	DBGFFLOWTRACEPROBEENTRYTYPE_INDIRECT_MEM,
93	/** Callback. */
94	DBGFFLOWTRACEPROBEENTRYTYPE_CALLBACK,
95	/** 32bit hack. */
96	DBGFFLOWTRACEPROBEENTRYTYPE_32BIT_HACK = 0x7fffffff
97	} DBGFFLOWTRACEPROBEENTRYTYPE;
98
99
100	/**
101	* Register descriptor for a probe entry.
102	*/
103	typedef struct DBGFFLOWTRACEPROBEENTRYREG
104	{
105	/** The register name - see DBGFR3RegNm. /
106	const char *pszName;
107	/** The size of the value in bytes. */
108	DBGFREGVALTYPE enmType;
109	} DBGFFLOWTRACEPROBEENTRYREG;
110	/** Pointer to data probe register entry. */
111	typedef DBGFFLOWTRACEPROBEENTRYREG *PDBGFFLOWTRACEPROBEENTRYREG;
112	/** Pointer to a const probe register entry. */
113	typedef const DBGFFLOWTRACEPROBEENTRYREG *PCDBGFFLOWTRACEPROBEENTRYREG;
114
115
116	/**
117	* Flow trace probe callback.
118	*
119	* @returns VBox status code, any error aborts continuing fetching the data for the
120	* probe containing this callback.
121	* @param pUVM The usermode VM handle.
122	* @param idCpu The ID of the vCPU the probe as fired.
123	* @param hFlowTraceMod The handle to the flow trace module the probe was fired for.
124	* @param pAddrProbe The guest address the probe was fired at.
125	* @param hFlowTraceProbe The flow trace probe handle.this callback is in.
126	* @param pProbeEntry The probe entry this callback is part of.
127	* @param pvUser The opaque user data for the callback.
128	*/
129	typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEPROBECALLBACK, (PUVM pUVM, VMCPUID idCpu, DBGFFLOWTRACEMOD hFlowTraceMod,
130	PCDBGFADDRESS pAddrProbe, DBGFFLOWTRACEPROBE hFlowTraceProbe,
131	PCDBGFFLOWTRACEPROBEENTRY pProbeEntry,
132	void *pvUser));
133	/** Pointer to a flow trace probe callback. */
134	typedef FNDBGFFLOWTRACEPROBECALLBACK *PFNDBGFFLOWTRACEPROBECALLBACK;
135
136
137	/**
138	* Trace flow probe entry.
139	*/
140	typedef struct DBGFFLOWTRACEPROBEENTRY
141	{
142	/** Entry type. */
143	DBGFFLOWTRACEPROBEENTRYTYPE enmType;
144	/** Description for this entry, optional. */
145	const char *pszDesc;
146	/** The data based on the entry type. */
147	union
148	{
149	/** Register. */
150	DBGFFLOWTRACEPROBEENTRYREG Reg;
151	/** Constant memory pointer. */
152	struct
153	{
154	/** The address of the memory buffer. */
155	DBGFADDRESS AddrMem;
156	/** Number of bytes to log. */
157	size_t cbMem;
158	} ConstMem;
159	/** Indirect memory */
160	struct
161	{
162	/** The base register. */
163	DBGFFLOWTRACEPROBEENTRYREG RegBase;
164	/** The index register. */
165	DBGFFLOWTRACEPROBEENTRYREG RegIndex;
166	/** The scale to apply to the index. */
167	uint8_t uScale;
168	/** A constant offset which is applied at the end. */
169	RTGCINTPTR iOffset;
170	/** Number of bytes to log. */
171	size_t cbMem;
172	} IndirectMem;
173	/** Callback. */
174	struct
175	{
176	/** The callback to call. */
177	PFNDBGFFLOWTRACEPROBECALLBACK pfnCallback;
178	/** The opaque user data to provide. */
179	void *pvUser;
180	} Callback;
181	} Type;
182	} DBGFFLOWTRACEPROBEENTRY;
183
184
185	/**
186	* Flow trace probe value.
187	*/
188	typedef struct DBGFFLOWTRACEPROBEVAL
189	{
190	/** Pointer to the flow trace probe entry this value is for. */
191	PCDBGFFLOWTRACEPROBEENTRY pProbeEntry;
192	/** Data based on the type in the entry. */
193	union
194	{
195	/** Register value. */
196	DBGFREGENTRYNM Reg;
197	/** Memory value (constant pointer or indirect). */
198	struct
199	{
200	/** The guest address logged. */
201	DBGFADDRESS Addr;
202	/** Pointer to the data logged. */
203	const void *pvBuf;
204	/** Number of bytes logged. */
205	size_t cbBuf;
206	} Mem;
207	} Type;
208	} DBGFFLOWTRACEPROBEVAL;
209	/** Pointer to a flow trace probe value. */
210	typedef DBGFFLOWTRACEPROBEVAL *PDBGFFLOWTRACEPROBEVAL;
211	/** Pointer to a const flow trace probe value. */
212	typedef const DBGFFLOWTRACEPROBEVAL *PCDBGFFLOWTRACEPROBEVAL;
213
214	/**
215	* Flow trace report filter operation.
216	*/
217	typedef enum DBGFFLOWTRACEREPORTFILTEROP
218	{
219	/** Invalid filter operation. */
220	DBGFFLOWTRACEREPORTFILTEROP_INVALID = 0,
221	/** All filters must match with the record. */
222	DBGFFLOWTRACEREPORTFILTEROP_AND,
223	/** Only one filter must match with the record. */
224	DBGFFLOWTRACEREPORTFILTEROP_OR,
225	/** 32bit hack. */
226	DBGFFLOWTRACEREPORTFILTEROP_32BIT_HACK = 0x7fffffff
227	} DBGFFLOWTRACEREPORTFILTEROP;
228
229
230	/**
231	* Flow trace report filter type.
232	*/
233	typedef enum DBGFFLOWTRACEREPORTFILTERTYPE
234	{
235	/** Invalid filter type. */
236	DBGFFLOWTRACEREPORTFILTERTYPE_INVALID = 0,
237	/** Filter by sequence number. */
238	DBGFFLOWTRACEREPORTFILTERTYPE_SEQ_NUM,
239	/** Filter by timestamp. */
240	DBGFFLOWTRACEREPORTFILTERTYPE_TIMESTAMP,
241	/** Filter by probe address. */
242	DBGFFLOWTRACEREPORTFILTERTYPE_ADDR,
243	/** Filter by CPU ID. */
244	DBGFFLOWTRACEREPORTFILTERTYPE_VMCPU_ID,
245	/** Filter by specific probe data. */
246	DBGFFLOWTRACEREPORTFILTERTYPE_PROBE_DATA,
247	/** 32bit hack. */
248	DBGFFLOWTRACEREPORTFILTERTYPE_32BIT_HACK = 0x7fffffff
249	} DBGFFLOWTRACEREPORTFILTERTYPE;
250
251
252	/**
253	* Flow trace report filter.
254	*/
255	typedef struct DBGFFLOWTRACEREPORTFILTER
256	{
257	/** Filter type. */
258	DBGFFLOWTRACEREPORTFILTERTYPE enmType;
259	/** Filter data, type dependent. */
260	struct
261	{
262	/** Sequence number filtering. */
263	struct
264	{
265	/** Sequence number filtering, start value. */
266	uint64_t u64SeqNoFirst;
267	/** Sequence number filtering, last value. */
268	uint64_t u64SeqNoLast;
269	} SeqNo;
270	/** Timestamp filtering. */
271	struct
272	{
273	/** Start value. */
274	uint64_t u64TsFirst;
275	/** Last value. */
276	uint64_t u64TsLast;
277	} Timestamp;
278	/** Probe address filtering. */
279	struct
280	{
281	/** Start address. */
282	DBGFADDRESS AddrStart;
283	/** Last address. */
284	DBGFADDRESS AddrLast;
285	} Addr;
286	/** vCPU id filtering. */
287	struct
288	{
289	/** Start CPU id. */
290	VMCPUID idCpuStart;
291	/** Last CPU id. */
292	VMCPUID idCpuLast;
293	} VCpuId;
294	/** Probe data filtering. */
295	struct
296	{
297	/** Pointer to the probe value array. */
298	PCDBGFFLOWTRACEPROBEVAL paVal;
299	/** Number of entries in the array for filtering. */
300	uint32_t cVals;
301	/** Flag whether to look into the common values or the probe specific ones. */
302	bool fValCmn;
303	} ProbeData;
304	} Type;
305	} DBGFFLOWTRACEREPORTFILTER;
306	/** Pointer to a flow trace report filter. */
307	typedef DBGFFLOWTRACEREPORTFILTER *PDBGFFLOWTRACEREPORTFILTER;
308
309
310	/** @name Flags controlling filtering records.
311	* @{ */
312	/** Add records which don't match the filter. */
313	#define DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE RT_BIT_32(0)
314	/** Mask of all valid flags. */
315	#define DBGF_FLOW_TRACE_REPORT_FILTER_F_VALID (DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE)
316	/** @} */
317
318
319	/**
320	* Flow trace report enumeration callback.
321	*
322	* @returns VBox status code, any non VINF_SUCCESS code aborts the enumeration and is returned
323	* by DBGFR3FlowTraceReportEnumRecords().
324	* @param hFlowTraceReport The flow trace report handle being enumerated.
325	* @param hFlowTraceRecord The flow trace record handle.
326	* @param pvUser Opaque user data given in DBGFR3FlowTraceReportEnumRecords().
327	*/
328	typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEREPORTENUMCLBK,(DBGFFLOWTRACEREPORT hFlowTraceReport,
329	DBGFFLOWTRACERECORD hFlowTraceRecord,
330	void *pvUser));
331	/** Pointer to a record enumeration callback. */
332	typedef FNDBGFFLOWTRACEREPORTENUMCLBK *PFNDBGFFLOWTRACEREPORTENUMCLBK;
333
334
335	VMMR3DECL(int) DBGFR3FlowTraceModCreate(PUVM pUVM, VMCPUID idCpu,
336	DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
337	PDBGFFLOWTRACEMOD phFlowTraceMod);
338	VMMR3DECL(int) DBGFR3FlowTraceModCreateFromFlowGraph(PUVM pUVM, VMCPUID idCpu, DBGFFLOW hFlow,
339	DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
340	DBGFFLOWTRACEPROBE hFlowTraceProbeEntry,
341	DBGFFLOWTRACEPROBE hFlowTraceProbeRegular,
342	DBGFFLOWTRACEPROBE hFlowTraceProbeExit,
343	PDBGFFLOWTRACEMOD phFlowTraceMod);
344	VMMR3DECL(uint32_t) DBGFR3FlowTraceModRetain(DBGFFLOWTRACEMOD hFlowTraceMod);
345	VMMR3DECL(uint32_t) DBGFR3FlowTraceModRelease(DBGFFLOWTRACEMOD hFlowTraceMod);
346	VMMR3DECL(int) DBGFR3FlowTraceModEnable(DBGFFLOWTRACEMOD hFlowTraceMod, uint32_t cHits, uint32_t cRecordsMax);
347	VMMR3DECL(int) DBGFR3FlowTraceModDisable(DBGFFLOWTRACEMOD hFlowTraceMod);
348	VMMR3DECL(int) DBGFR3FlowTraceModQueryReport(DBGFFLOWTRACEMOD hFlowTraceMod,
349	PDBGFFLOWTRACEREPORT phFlowTraceReport);
350	VMMR3DECL(int) DBGFR3FlowTraceModClear(DBGFFLOWTRACEMOD hFlowTraceMod);
351	VMMR3DECL(int) DBGFR3FlowTraceModAddProbe(DBGFFLOWTRACEMOD hFlowTraceMod, PCDBGFADDRESS pAddrProbe,
352	DBGFFLOWTRACEPROBE hFlowTraceProbe, uint32_t fFlags);
353
354	VMMR3DECL(int) DBGFR3FlowTraceProbeCreate(PUVM pUVM, const char *pszDescr, PDBGFFLOWTRACEPROBE phFlowTraceProbe);
355	VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRetain(DBGFFLOWTRACEPROBE hFlowTraceProbe);
356	VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRelease(DBGFFLOWTRACEPROBE hFlowTraceProbe);
357	VMMR3DECL(int) DBGFR3FlowTraceProbeEntriesAdd(DBGFFLOWTRACEPROBE hFlowTraceProbe,
358	PCDBGFFLOWTRACEPROBEENTRY paEntries, uint32_t cEntries);
359
360	VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRetain(DBGFFLOWTRACEREPORT hFlowTraceReport);
361	VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRelease(DBGFFLOWTRACEREPORT hFlowTraceReport);
362	VMMR3DECL(uint32_t) DBGFR3FlowTraceReportGetRecordCount(DBGFFLOWTRACEREPORT hFlowTraceReport);
363	VMMR3DECL(int) DBGFR3FlowTraceReportQueryFiltered(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t fFlags,
364	PDBGFFLOWTRACEREPORTFILTER paFilters, uint32_t cFilters,
365	DBGFFLOWTRACEREPORTFILTEROP enmOp,
366	PDBGFFLOWTRACEREPORT phFlowTraceReportFiltered);
367	VMMR3DECL(int) DBGFR3FlowTraceReportEnumRecords(DBGFFLOWTRACEREPORT hFlowTraceReport,
368	PFNDBGFFLOWTRACEREPORTENUMCLBK pfnEnum,
369	void *pvUser);
370
371	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRetain(DBGFFLOWTRACERECORD hFlowTraceRecord);
372	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRelease(DBGFFLOWTRACERECORD hFlowTraceRecord);
373	VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetSeqNo(DBGFFLOWTRACERECORD hFlowTraceRecord);
374	VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetTimestamp(DBGFFLOWTRACERECORD hFlowTraceRecord);
375	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowTraceRecordGetAddr(DBGFFLOWTRACERECORD hFlowTraceRecord, PDBGFADDRESS pAddr);
376	VMMR3DECL(DBGFFLOWTRACEPROBE) DBGFR3FlowTraceRecordGetProbe(DBGFFLOWTRACERECORD hFlowTraceRecord);
377	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
378	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCommonCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
379	VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetVals(DBGFFLOWTRACERECORD hFlowTraceRecord);
380	VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetValsCommon(DBGFFLOWTRACERECORD hFlowTraceRecord);
381	VMMR3DECL(VMCPUID) DBGFR3FlowTraceRecordGetCpuId(DBGFFLOWTRACERECORD hFlowTraceRecord);
382
383	/** @} */
384	RT_C_DECLS_END
385
386	#endif /* !VBOX_INCLUDED_vmm_dbgfflowtrace_h */
387

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

source: vbox/trunk/include/VBox/vmm/dbgfflowtrace.h@ 87518

Download in other formats: