VirtualBox

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

Last change on this file since 88534 was 87787, checked in by vboxsync, 4 years ago

VMM/DBGFR3FlowTrace*: Add some API to query a record based on the index, bugref:8650
  • 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 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
35RT_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. */
43typedef struct DBGFFLOWTRACEMODINT *DBGFFLOWTRACEMOD;
44/** Pointer to a DBGF flow trace module handle. */
45typedef DBGFFLOWTRACEMOD *PDBGFFLOWTRACEMOD;
46/** A DBGF flow trace probe handle. */
47typedef struct DBGFFLOWTRACEPROBEINT *DBGFFLOWTRACEPROBE;
48/** Pointer to a DBGF flow trace state probe handle. */
49typedef DBGFFLOWTRACEPROBE *PDBGFFLOWTRACEPROBE;
50/** A DBGF flow trace report handle. */
51typedef struct DBGFFLOWTRACEREPORTINT *DBGFFLOWTRACEREPORT;
52/** Pointer to a DBGF flow trace report handle. */
53typedef DBGFFLOWTRACEREPORT *PDBGFFLOWTRACEREPORT;
54/** A DBGF flow trace record handle. */
55typedef struct DBGFFLOWTRACERECORDINT *DBGFFLOWTRACERECORD;
56/** Pointer to a DBGF flow trace record handle. */
57typedef DBGFFLOWTRACERECORD *PDBGFFLOWTRACERECORD;
58
59
60/** Pointer to a flow trace probe entry. */
61typedef struct DBGFFLOWTRACEPROBEENTRY *PDBGFFLOWTRACEPROBEENTRY;
62/** Pointer to a const flow trace probe entry. */
63typedef 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 */
82typedef 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 */
105typedef 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. */
113typedef DBGFFLOWTRACEPROBEENTRYREG *PDBGFFLOWTRACEPROBEENTRYREG;
114/** Pointer to a const probe register entry. */
115typedef 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 */
131typedef 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. */
136typedef FNDBGFFLOWTRACEPROBECALLBACK *PFNDBGFFLOWTRACEPROBECALLBACK;
137
138
139/**
140 * Trace flow probe entry.
141 */
142typedef 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 */
190typedef 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. */
212typedef DBGFFLOWTRACEPROBEVAL *PDBGFFLOWTRACEPROBEVAL;
213/** Pointer to a const flow trace probe value. */
214typedef const DBGFFLOWTRACEPROBEVAL *PCDBGFFLOWTRACEPROBEVAL;
215
216/**
217 * Flow trace report filter operation.
218 */
219typedef 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 */
235typedef 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 */
257typedef 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. */
309typedef 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 */
330typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEREPORTENUMCLBK,(DBGFFLOWTRACEREPORT hFlowTraceReport,
331 DBGFFLOWTRACERECORD hFlowTraceRecord,
332 void *pvUser));
333/** Pointer to a record enumeration callback. */
334typedef FNDBGFFLOWTRACEREPORTENUMCLBK *PFNDBGFFLOWTRACEREPORTENUMCLBK;
335
336
337VMMR3DECL(int) DBGFR3FlowTraceModCreate(PUVM pUVM, VMCPUID idCpu,
338 DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
339 PDBGFFLOWTRACEMOD phFlowTraceMod);
340VMMR3DECL(int) DBGFR3FlowTraceModCreateFromFlowGraph(PUVM pUVM, VMCPUID idCpu, DBGFFLOW hFlow,
341 DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
342 DBGFFLOWTRACEPROBE hFlowTraceProbeEntry,
343 DBGFFLOWTRACEPROBE hFlowTraceProbeRegular,
344 DBGFFLOWTRACEPROBE hFlowTraceProbeExit,
345 PDBGFFLOWTRACEMOD phFlowTraceMod);
346VMMR3DECL(uint32_t) DBGFR3FlowTraceModRetain(DBGFFLOWTRACEMOD hFlowTraceMod);
347VMMR3DECL(uint32_t) DBGFR3FlowTraceModRelease(DBGFFLOWTRACEMOD hFlowTraceMod);
348VMMR3DECL(int) DBGFR3FlowTraceModEnable(DBGFFLOWTRACEMOD hFlowTraceMod, uint32_t cHits, uint32_t cRecordsMax);
349VMMR3DECL(int) DBGFR3FlowTraceModDisable(DBGFFLOWTRACEMOD hFlowTraceMod);
350VMMR3DECL(int) DBGFR3FlowTraceModQueryReport(DBGFFLOWTRACEMOD hFlowTraceMod,
351 PDBGFFLOWTRACEREPORT phFlowTraceReport);
352VMMR3DECL(int) DBGFR3FlowTraceModClear(DBGFFLOWTRACEMOD hFlowTraceMod);
353VMMR3DECL(int) DBGFR3FlowTraceModAddProbe(DBGFFLOWTRACEMOD hFlowTraceMod, PCDBGFADDRESS pAddrProbe,
354 DBGFFLOWTRACEPROBE hFlowTraceProbe, uint32_t fFlags);
355
356VMMR3DECL(int) DBGFR3FlowTraceProbeCreate(PUVM pUVM, const char *pszDescr, PDBGFFLOWTRACEPROBE phFlowTraceProbe);
357VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRetain(DBGFFLOWTRACEPROBE hFlowTraceProbe);
358VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRelease(DBGFFLOWTRACEPROBE hFlowTraceProbe);
359VMMR3DECL(int) DBGFR3FlowTraceProbeEntriesAdd(DBGFFLOWTRACEPROBE hFlowTraceProbe,
360 PCDBGFFLOWTRACEPROBEENTRY paEntries, uint32_t cEntries);
361
362VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRetain(DBGFFLOWTRACEREPORT hFlowTraceReport);
363VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRelease(DBGFFLOWTRACEREPORT hFlowTraceReport);
364VMMR3DECL(uint32_t) DBGFR3FlowTraceReportGetRecordCount(DBGFFLOWTRACEREPORT hFlowTraceReport);
365VMMR3DECL(int) DBGFR3FlowTraceReportQueryRecord(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t idxRec, PDBGFFLOWTRACERECORD phFlowTraceRec);
366VMMR3DECL(int) DBGFR3FlowTraceReportQueryFiltered(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t fFlags,
367 PDBGFFLOWTRACEREPORTFILTER paFilters, uint32_t cFilters,
368 DBGFFLOWTRACEREPORTFILTEROP enmOp,
369 PDBGFFLOWTRACEREPORT phFlowTraceReportFiltered);
370VMMR3DECL(int) DBGFR3FlowTraceReportEnumRecords(DBGFFLOWTRACEREPORT hFlowTraceReport,
371 PFNDBGFFLOWTRACEREPORTENUMCLBK pfnEnum,
372 void *pvUser);
373
374VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRetain(DBGFFLOWTRACERECORD hFlowTraceRecord);
375VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRelease(DBGFFLOWTRACERECORD hFlowTraceRecord);
376VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetSeqNo(DBGFFLOWTRACERECORD hFlowTraceRecord);
377VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetTimestamp(DBGFFLOWTRACERECORD hFlowTraceRecord);
378VMMR3DECL(PDBGFADDRESS) DBGFR3FlowTraceRecordGetAddr(DBGFFLOWTRACERECORD hFlowTraceRecord, PDBGFADDRESS pAddr);
379VMMR3DECL(DBGFFLOWTRACEPROBE) DBGFR3FlowTraceRecordGetProbe(DBGFFLOWTRACERECORD hFlowTraceRecord);
380VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
381VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCommonCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
382VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetVals(DBGFFLOWTRACERECORD hFlowTraceRecord);
383VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetValsCommon(DBGFFLOWTRACERECORD hFlowTraceRecord);
384VMMR3DECL(VMCPUID) DBGFR3FlowTraceRecordGetCpuId(DBGFFLOWTRACERECORD hFlowTraceRecord);
385
386/** @} */
387RT_C_DECLS_END
388
389#endif /* !VBOX_INCLUDED_vmm_dbgfflowtrace_h */
390
Note: See TracBrowser for help on using the repository browser.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette