VirtualBox

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

Last change on this file was 98103, checked in by vboxsync, 16 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
45RT_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. */
53typedef struct DBGFFLOWTRACEMODINT *DBGFFLOWTRACEMOD;
54/** Pointer to a DBGF flow trace module handle. */
55typedef DBGFFLOWTRACEMOD *PDBGFFLOWTRACEMOD;
56/** A DBGF flow trace probe handle. */
57typedef struct DBGFFLOWTRACEPROBEINT *DBGFFLOWTRACEPROBE;
58/** Pointer to a DBGF flow trace state probe handle. */
59typedef DBGFFLOWTRACEPROBE *PDBGFFLOWTRACEPROBE;
60/** A DBGF flow trace report handle. */
61typedef struct DBGFFLOWTRACEREPORTINT *DBGFFLOWTRACEREPORT;
62/** Pointer to a DBGF flow trace report handle. */
63typedef DBGFFLOWTRACEREPORT *PDBGFFLOWTRACEREPORT;
64/** A DBGF flow trace record handle. */
65typedef struct DBGFFLOWTRACERECORDINT *DBGFFLOWTRACERECORD;
66/** Pointer to a DBGF flow trace record handle. */
67typedef DBGFFLOWTRACERECORD *PDBGFFLOWTRACERECORD;
68
69
70/** Pointer to a flow trace probe entry. */
71typedef struct DBGFFLOWTRACEPROBEENTRY *PDBGFFLOWTRACEPROBEENTRY;
72/** Pointer to a const flow trace probe entry. */
73typedef 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 */
92typedef 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 */
115typedef 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. */
123typedef DBGFFLOWTRACEPROBEENTRYREG *PDBGFFLOWTRACEPROBEENTRYREG;
124/** Pointer to a const probe register entry. */
125typedef 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 */
141typedef 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. */
146typedef FNDBGFFLOWTRACEPROBECALLBACK *PFNDBGFFLOWTRACEPROBECALLBACK;
147
148
149/**
150 * Trace flow probe entry.
151 */
152typedef 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 */
200typedef 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. */
222typedef DBGFFLOWTRACEPROBEVAL *PDBGFFLOWTRACEPROBEVAL;
223/** Pointer to a const flow trace probe value. */
224typedef const DBGFFLOWTRACEPROBEVAL *PCDBGFFLOWTRACEPROBEVAL;
225
226/**
227 * Flow trace report filter operation.
228 */
229typedef 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 */
245typedef 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 */
267typedef 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. */
319typedef 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 */
340typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEREPORTENUMCLBK,(DBGFFLOWTRACEREPORT hFlowTraceReport,
341 DBGFFLOWTRACERECORD hFlowTraceRecord,
342 void *pvUser));
343/** Pointer to a record enumeration callback. */
344typedef FNDBGFFLOWTRACEREPORTENUMCLBK *PFNDBGFFLOWTRACEREPORTENUMCLBK;
345
346
347VMMR3DECL(int) DBGFR3FlowTraceModCreate(PUVM pUVM, VMCPUID idCpu,
348 DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
349 PDBGFFLOWTRACEMOD phFlowTraceMod);
350VMMR3DECL(int) DBGFR3FlowTraceModCreateFromFlowGraph(PUVM pUVM, VMCPUID idCpu, DBGFFLOW hFlow,
351 DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
352 DBGFFLOWTRACEPROBE hFlowTraceProbeEntry,
353 DBGFFLOWTRACEPROBE hFlowTraceProbeRegular,
354 DBGFFLOWTRACEPROBE hFlowTraceProbeExit,
355 PDBGFFLOWTRACEMOD phFlowTraceMod);
356VMMR3DECL(uint32_t) DBGFR3FlowTraceModRetain(DBGFFLOWTRACEMOD hFlowTraceMod);
357VMMR3DECL(uint32_t) DBGFR3FlowTraceModRelease(DBGFFLOWTRACEMOD hFlowTraceMod);
358VMMR3DECL(int) DBGFR3FlowTraceModEnable(DBGFFLOWTRACEMOD hFlowTraceMod, uint32_t cHits, uint32_t cRecordsMax);
359VMMR3DECL(int) DBGFR3FlowTraceModDisable(DBGFFLOWTRACEMOD hFlowTraceMod);
360VMMR3DECL(int) DBGFR3FlowTraceModQueryReport(DBGFFLOWTRACEMOD hFlowTraceMod,
361 PDBGFFLOWTRACEREPORT phFlowTraceReport);
362VMMR3DECL(int) DBGFR3FlowTraceModClear(DBGFFLOWTRACEMOD hFlowTraceMod);
363VMMR3DECL(int) DBGFR3FlowTraceModAddProbe(DBGFFLOWTRACEMOD hFlowTraceMod, PCDBGFADDRESS pAddrProbe,
364 DBGFFLOWTRACEPROBE hFlowTraceProbe, uint32_t fFlags);
365
366VMMR3DECL(int) DBGFR3FlowTraceProbeCreate(PUVM pUVM, const char *pszDescr, PDBGFFLOWTRACEPROBE phFlowTraceProbe);
367VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRetain(DBGFFLOWTRACEPROBE hFlowTraceProbe);
368VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRelease(DBGFFLOWTRACEPROBE hFlowTraceProbe);
369VMMR3DECL(int) DBGFR3FlowTraceProbeEntriesAdd(DBGFFLOWTRACEPROBE hFlowTraceProbe,
370 PCDBGFFLOWTRACEPROBEENTRY paEntries, uint32_t cEntries);
371
372VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRetain(DBGFFLOWTRACEREPORT hFlowTraceReport);
373VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRelease(DBGFFLOWTRACEREPORT hFlowTraceReport);
374VMMR3DECL(uint32_t) DBGFR3FlowTraceReportGetRecordCount(DBGFFLOWTRACEREPORT hFlowTraceReport);
375VMMR3DECL(int) DBGFR3FlowTraceReportQueryRecord(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t idxRec, PDBGFFLOWTRACERECORD phFlowTraceRec);
376VMMR3DECL(int) DBGFR3FlowTraceReportQueryFiltered(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t fFlags,
377 PDBGFFLOWTRACEREPORTFILTER paFilters, uint32_t cFilters,
378 DBGFFLOWTRACEREPORTFILTEROP enmOp,
379 PDBGFFLOWTRACEREPORT phFlowTraceReportFiltered);
380VMMR3DECL(int) DBGFR3FlowTraceReportEnumRecords(DBGFFLOWTRACEREPORT hFlowTraceReport,
381 PFNDBGFFLOWTRACEREPORTENUMCLBK pfnEnum,
382 void *pvUser);
383
384VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRetain(DBGFFLOWTRACERECORD hFlowTraceRecord);
385VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRelease(DBGFFLOWTRACERECORD hFlowTraceRecord);
386VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetSeqNo(DBGFFLOWTRACERECORD hFlowTraceRecord);
387VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetTimestamp(DBGFFLOWTRACERECORD hFlowTraceRecord);
388VMMR3DECL(PDBGFADDRESS) DBGFR3FlowTraceRecordGetAddr(DBGFFLOWTRACERECORD hFlowTraceRecord, PDBGFADDRESS pAddr);
389VMMR3DECL(DBGFFLOWTRACEPROBE) DBGFR3FlowTraceRecordGetProbe(DBGFFLOWTRACERECORD hFlowTraceRecord);
390VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
391VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCommonCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
392VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetVals(DBGFFLOWTRACERECORD hFlowTraceRecord);
393VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetValsCommon(DBGFFLOWTRACERECORD hFlowTraceRecord);
394VMMR3DECL(VMCPUID) DBGFR3FlowTraceRecordGetCpuId(DBGFFLOWTRACERECORD hFlowTraceRecord);
395
396/** @} */
397RT_C_DECLS_END
398
399#endif /* !VBOX_INCLUDED_vmm_dbgfflowtrace_h */
400
Note: See TracBrowser for help on using the repository browser.

© 2023 Oracle
Contact – Privacy policy – Terms of Use