dbgfflowtrace.h@ 93963

Last change on this file since 93963 was 93115, checked in by vboxsync, 3 years ago
scm --update-copyright-year
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.4 KB

Line
1	/** @file
2	* DBGF - Debugger Facility, Guest execution flow tracing.
3	*/
4
5	/*
6	* Copyright (C) 2020-2022 Oracle Corporation
7	*
8	* This file is part of VirtualBox Open Source Edition (OSE), as
9	* available from http://www.virtualbox.org. This file is free software;
10	* you can redistribute it and/or modify it under the terms of the GNU
11	* General Public License (GPL) as published by the Free Software
12	* Foundation, in version 2 as it comes in the "COPYING" file of the
13	* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
14	* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
15	*
16	* The contents of this file may alternatively be used under the terms
17	* of the Common Development and Distribution License Version 1.0
18	* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
19	* VirtualBox OSE distribution, in which case the provisions of the
20	* CDDL are applicable instead of those of the GPL.
21	*
22	* You may elect to license modified versions of this file under the
23	* terms and conditions of either the GPL or the CDDL or both.
24	*/
25
26	#ifndef VBOX_INCLUDED_vmm_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	/** Halt in the debugger when the entry is collected. */
96	DBGFFLOWTRACEPROBEENTRYTYPE_DEBUGGER,
97	/** 32bit hack. */
98	DBGFFLOWTRACEPROBEENTRYTYPE_32BIT_HACK = 0x7fffffff
99	} DBGFFLOWTRACEPROBEENTRYTYPE;
100
101
102	/**
103	* Register descriptor for a probe entry.
104	*/
105	typedef struct DBGFFLOWTRACEPROBEENTRYREG
106	{
107	/** The register name - see DBGFR3RegNm. /
108	const char *pszName;
109	/** The size of the value in bytes. */
110	DBGFREGVALTYPE enmType;
111	} DBGFFLOWTRACEPROBEENTRYREG;
112	/** Pointer to data probe register entry. */
113	typedef DBGFFLOWTRACEPROBEENTRYREG *PDBGFFLOWTRACEPROBEENTRYREG;
114	/** Pointer to a const probe register entry. */
115	typedef const DBGFFLOWTRACEPROBEENTRYREG *PCDBGFFLOWTRACEPROBEENTRYREG;
116
117
118	/**
119	* Flow trace probe callback.
120	*
121	* @returns VBox status code, any error aborts continuing fetching the data for the
122	* probe containing this callback.
123	* @param pUVM The usermode VM handle.
124	* @param idCpu The ID of the vCPU the probe as fired.
125	* @param hFlowTraceMod The handle to the flow trace module the probe was fired for.
126	* @param pAddrProbe The guest address the probe was fired at.
127	* @param hFlowTraceProbe The flow trace probe handle.this callback is in.
128	* @param pProbeEntry The probe entry this callback is part of.
129	* @param pvUser The opaque user data for the callback.
130	*/
131	typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEPROBECALLBACK, (PUVM pUVM, VMCPUID idCpu, DBGFFLOWTRACEMOD hFlowTraceMod,
132	PCDBGFADDRESS pAddrProbe, DBGFFLOWTRACEPROBE hFlowTraceProbe,
133	PCDBGFFLOWTRACEPROBEENTRY pProbeEntry,
134	void *pvUser));
135	/** Pointer to a flow trace probe callback. */
136	typedef FNDBGFFLOWTRACEPROBECALLBACK *PFNDBGFFLOWTRACEPROBECALLBACK;
137
138
139	/**
140	* Trace flow probe entry.
141	*/
142	typedef struct DBGFFLOWTRACEPROBEENTRY
143	{
144	/** Entry type. */
145	DBGFFLOWTRACEPROBEENTRYTYPE enmType;
146	/** Description for this entry, optional. */
147	const char *pszDesc;
148	/** The data based on the entry type. */
149	union
150	{
151	/** Register. */
152	DBGFFLOWTRACEPROBEENTRYREG Reg;
153	/** Constant memory pointer. */
154	struct
155	{
156	/** The address of the memory buffer. */
157	DBGFADDRESS AddrMem;
158	/** Number of bytes to log. */
159	size_t cbMem;
160	} ConstMem;
161	/** Indirect memory */
162	struct
163	{
164	/** The base register. */
165	DBGFFLOWTRACEPROBEENTRYREG RegBase;
166	/** The index register. */
167	DBGFFLOWTRACEPROBEENTRYREG RegIndex;
168	/** The scale to apply to the index. */
169	uint8_t uScale;
170	/** A constant offset which is applied at the end. */
171	RTGCINTPTR iOffset;
172	/** Number of bytes to log. */
173	size_t cbMem;
174	} IndirectMem;
175	/** Callback. */
176	struct
177	{
178	/** The callback to call. */
179	PFNDBGFFLOWTRACEPROBECALLBACK pfnCallback;
180	/** The opaque user data to provide. */
181	void *pvUser;
182	} Callback;
183	} Type;
184	} DBGFFLOWTRACEPROBEENTRY;
185
186
187	/**
188	* Flow trace probe value.
189	*/
190	typedef struct DBGFFLOWTRACEPROBEVAL
191	{
192	/** Pointer to the flow trace probe entry this value is for. */
193	PCDBGFFLOWTRACEPROBEENTRY pProbeEntry;
194	/** Data based on the type in the entry. */
195	union
196	{
197	/** Register value. */
198	DBGFREGENTRYNM Reg;
199	/** Memory value (constant pointer or indirect). */
200	struct
201	{
202	/** The guest address logged. */
203	DBGFADDRESS Addr;
204	/** Pointer to the data logged. */
205	const void *pvBuf;
206	/** Number of bytes logged. */
207	size_t cbBuf;
208	} Mem;
209	} Type;
210	} DBGFFLOWTRACEPROBEVAL;
211	/** Pointer to a flow trace probe value. */
212	typedef DBGFFLOWTRACEPROBEVAL *PDBGFFLOWTRACEPROBEVAL;
213	/** Pointer to a const flow trace probe value. */
214	typedef const DBGFFLOWTRACEPROBEVAL *PCDBGFFLOWTRACEPROBEVAL;
215
216	/**
217	* Flow trace report filter operation.
218	*/
219	typedef enum DBGFFLOWTRACEREPORTFILTEROP
220	{
221	/** Invalid filter operation. */
222	DBGFFLOWTRACEREPORTFILTEROP_INVALID = 0,
223	/** All filters must match with the record. */
224	DBGFFLOWTRACEREPORTFILTEROP_AND,
225	/** Only one filter must match with the record. */
226	DBGFFLOWTRACEREPORTFILTEROP_OR,
227	/** 32bit hack. */
228	DBGFFLOWTRACEREPORTFILTEROP_32BIT_HACK = 0x7fffffff
229	} DBGFFLOWTRACEREPORTFILTEROP;
230
231
232	/**
233	* Flow trace report filter type.
234	*/
235	typedef enum DBGFFLOWTRACEREPORTFILTERTYPE
236	{
237	/** Invalid filter type. */
238	DBGFFLOWTRACEREPORTFILTERTYPE_INVALID = 0,
239	/** Filter by sequence number. */
240	DBGFFLOWTRACEREPORTFILTERTYPE_SEQ_NUM,
241	/** Filter by timestamp. */
242	DBGFFLOWTRACEREPORTFILTERTYPE_TIMESTAMP,
243	/** Filter by probe address. */
244	DBGFFLOWTRACEREPORTFILTERTYPE_ADDR,
245	/** Filter by CPU ID. */
246	DBGFFLOWTRACEREPORTFILTERTYPE_VMCPU_ID,
247	/** Filter by specific probe data. */
248	DBGFFLOWTRACEREPORTFILTERTYPE_PROBE_DATA,
249	/** 32bit hack. */
250	DBGFFLOWTRACEREPORTFILTERTYPE_32BIT_HACK = 0x7fffffff
251	} DBGFFLOWTRACEREPORTFILTERTYPE;
252
253
254	/**
255	* Flow trace report filter.
256	*/
257	typedef struct DBGFFLOWTRACEREPORTFILTER
258	{
259	/** Filter type. */
260	DBGFFLOWTRACEREPORTFILTERTYPE enmType;
261	/** Filter data, type dependent. */
262	struct
263	{
264	/** Sequence number filtering. */
265	struct
266	{
267	/** Sequence number filtering, start value. */
268	uint64_t u64SeqNoFirst;
269	/** Sequence number filtering, last value. */
270	uint64_t u64SeqNoLast;
271	} SeqNo;
272	/** Timestamp filtering. */
273	struct
274	{
275	/** Start value. */
276	uint64_t u64TsFirst;
277	/** Last value. */
278	uint64_t u64TsLast;
279	} Timestamp;
280	/** Probe address filtering. */
281	struct
282	{
283	/** Start address. */
284	DBGFADDRESS AddrStart;
285	/** Last address. */
286	DBGFADDRESS AddrLast;
287	} Addr;
288	/** vCPU id filtering. */
289	struct
290	{
291	/** Start CPU id. */
292	VMCPUID idCpuStart;
293	/** Last CPU id. */
294	VMCPUID idCpuLast;
295	} VCpuId;
296	/** Probe data filtering. */
297	struct
298	{
299	/** Pointer to the probe value array. */
300	PCDBGFFLOWTRACEPROBEVAL paVal;
301	/** Number of entries in the array for filtering. */
302	uint32_t cVals;
303	/** Flag whether to look into the common values or the probe specific ones. */
304	bool fValCmn;
305	} ProbeData;
306	} Type;
307	} DBGFFLOWTRACEREPORTFILTER;
308	/** Pointer to a flow trace report filter. */
309	typedef DBGFFLOWTRACEREPORTFILTER *PDBGFFLOWTRACEREPORTFILTER;
310
311
312	/** @name Flags controlling filtering records.
313	* @{ */
314	/** Add records which don't match the filter. */
315	#define DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE RT_BIT_32(0)
316	/** Mask of all valid flags. */
317	#define DBGF_FLOW_TRACE_REPORT_FILTER_F_VALID (DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE)
318	/** @} */
319
320
321	/**
322	* Flow trace report enumeration callback.
323	*
324	* @returns VBox status code, any non VINF_SUCCESS code aborts the enumeration and is returned
325	* by DBGFR3FlowTraceReportEnumRecords().
326	* @param hFlowTraceReport The flow trace report handle being enumerated.
327	* @param hFlowTraceRecord The flow trace record handle.
328	* @param pvUser Opaque user data given in DBGFR3FlowTraceReportEnumRecords().
329	*/
330	typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEREPORTENUMCLBK,(DBGFFLOWTRACEREPORT hFlowTraceReport,
331	DBGFFLOWTRACERECORD hFlowTraceRecord,
332	void *pvUser));
333	/** Pointer to a record enumeration callback. */
334	typedef FNDBGFFLOWTRACEREPORTENUMCLBK *PFNDBGFFLOWTRACEREPORTENUMCLBK;
335
336
337	VMMR3DECL(int) DBGFR3FlowTraceModCreate(PUVM pUVM, VMCPUID idCpu,
338	DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
339	PDBGFFLOWTRACEMOD phFlowTraceMod);
340	VMMR3DECL(int) DBGFR3FlowTraceModCreateFromFlowGraph(PUVM pUVM, VMCPUID idCpu, DBGFFLOW hFlow,
341	DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
342	DBGFFLOWTRACEPROBE hFlowTraceProbeEntry,
343	DBGFFLOWTRACEPROBE hFlowTraceProbeRegular,
344	DBGFFLOWTRACEPROBE hFlowTraceProbeExit,
345	PDBGFFLOWTRACEMOD phFlowTraceMod);
346	VMMR3DECL(uint32_t) DBGFR3FlowTraceModRetain(DBGFFLOWTRACEMOD hFlowTraceMod);
347	VMMR3DECL(uint32_t) DBGFR3FlowTraceModRelease(DBGFFLOWTRACEMOD hFlowTraceMod);
348	VMMR3DECL(int) DBGFR3FlowTraceModEnable(DBGFFLOWTRACEMOD hFlowTraceMod, uint32_t cHits, uint32_t cRecordsMax);
349	VMMR3DECL(int) DBGFR3FlowTraceModDisable(DBGFFLOWTRACEMOD hFlowTraceMod);
350	VMMR3DECL(int) DBGFR3FlowTraceModQueryReport(DBGFFLOWTRACEMOD hFlowTraceMod,
351	PDBGFFLOWTRACEREPORT phFlowTraceReport);
352	VMMR3DECL(int) DBGFR3FlowTraceModClear(DBGFFLOWTRACEMOD hFlowTraceMod);
353	VMMR3DECL(int) DBGFR3FlowTraceModAddProbe(DBGFFLOWTRACEMOD hFlowTraceMod, PCDBGFADDRESS pAddrProbe,
354	DBGFFLOWTRACEPROBE hFlowTraceProbe, uint32_t fFlags);
355
356	VMMR3DECL(int) DBGFR3FlowTraceProbeCreate(PUVM pUVM, const char *pszDescr, PDBGFFLOWTRACEPROBE phFlowTraceProbe);
357	VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRetain(DBGFFLOWTRACEPROBE hFlowTraceProbe);
358	VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRelease(DBGFFLOWTRACEPROBE hFlowTraceProbe);
359	VMMR3DECL(int) DBGFR3FlowTraceProbeEntriesAdd(DBGFFLOWTRACEPROBE hFlowTraceProbe,
360	PCDBGFFLOWTRACEPROBEENTRY paEntries, uint32_t cEntries);
361
362	VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRetain(DBGFFLOWTRACEREPORT hFlowTraceReport);
363	VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRelease(DBGFFLOWTRACEREPORT hFlowTraceReport);
364	VMMR3DECL(uint32_t) DBGFR3FlowTraceReportGetRecordCount(DBGFFLOWTRACEREPORT hFlowTraceReport);
365	VMMR3DECL(int) DBGFR3FlowTraceReportQueryRecord(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t idxRec, PDBGFFLOWTRACERECORD phFlowTraceRec);
366	VMMR3DECL(int) DBGFR3FlowTraceReportQueryFiltered(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t fFlags,
367	PDBGFFLOWTRACEREPORTFILTER paFilters, uint32_t cFilters,
368	DBGFFLOWTRACEREPORTFILTEROP enmOp,
369	PDBGFFLOWTRACEREPORT phFlowTraceReportFiltered);
370	VMMR3DECL(int) DBGFR3FlowTraceReportEnumRecords(DBGFFLOWTRACEREPORT hFlowTraceReport,
371	PFNDBGFFLOWTRACEREPORTENUMCLBK pfnEnum,
372	void *pvUser);
373
374	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRetain(DBGFFLOWTRACERECORD hFlowTraceRecord);
375	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRelease(DBGFFLOWTRACERECORD hFlowTraceRecord);
376	VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetSeqNo(DBGFFLOWTRACERECORD hFlowTraceRecord);
377	VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetTimestamp(DBGFFLOWTRACERECORD hFlowTraceRecord);
378	VMMR3DECL(PDBGFADDRESS) DBGFR3FlowTraceRecordGetAddr(DBGFFLOWTRACERECORD hFlowTraceRecord, PDBGFADDRESS pAddr);
379	VMMR3DECL(DBGFFLOWTRACEPROBE) DBGFR3FlowTraceRecordGetProbe(DBGFFLOWTRACERECORD hFlowTraceRecord);
380	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
381	VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCommonCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
382	VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetVals(DBGFFLOWTRACERECORD hFlowTraceRecord);
383	VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetValsCommon(DBGFFLOWTRACERECORD hFlowTraceRecord);
384	VMMR3DECL(VMCPUID) DBGFR3FlowTraceRecordGetCpuId(DBGFFLOWTRACERECORD hFlowTraceRecord);
385
386	/** @} */
387	RT_C_DECLS_END
388
389	#endif /* !VBOX_INCLUDED_vmm_dbgfflowtrace_h */
390

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

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

Download in other formats: