dbgfflowtrace.h@ 99896

Last change on this file since 99896 was 98103, checked in by vboxsync, 23 months ago
Copyright year updates by scm.
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 16.7 KB

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

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

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

Download in other formats: