summaryrefslogtreecommitdiffstats
path: root/include/VBox/vmm/dbgfflowtrace.h
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:49:04 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-04-07 16:49:04 +0000
commit16f504a9dca3fe3b70568f67b7d41241ae485288 (patch)
treec60f36ada0496ba928b7161059ba5ab1ab224f9d /include/VBox/vmm/dbgfflowtrace.h
parentInitial commit. (diff)
downloadvirtualbox-16f504a9dca3fe3b70568f67b7d41241ae485288.tar.xz
virtualbox-16f504a9dca3fe3b70568f67b7d41241ae485288.zip
Adding upstream version 7.0.6-dfsg.upstream/7.0.6-dfsgupstream
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'include/VBox/vmm/dbgfflowtrace.h')
-rw-r--r--include/VBox/vmm/dbgfflowtrace.h400
1 files changed, 400 insertions, 0 deletions
diff --git a/include/VBox/vmm/dbgfflowtrace.h b/include/VBox/vmm/dbgfflowtrace.h
new file mode 100644
index 00000000..4906fe7e
--- /dev/null
+++ b/include/VBox/vmm/dbgfflowtrace.h
@@ -0,0 +1,400 @@
+/** @file
+ * DBGF - Debugger Facility, Guest execution flow tracing.
+ */
+
+/*
+ * Copyright (C) 2020-2022 Oracle and/or its affiliates.
+ *
+ * This file is part of VirtualBox base platform packages, as
+ * available from https://www.virtualbox.org.
+ *
+ * This program is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU General Public License
+ * as published by the Free Software Foundation, in version 3 of the
+ * License.
+ *
+ * This program is distributed in the hope that it will be useful, but
+ * WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, see <https://www.gnu.org/licenses>.
+ *
+ * The contents of this file may alternatively be used under the terms
+ * of the Common Development and Distribution License Version 1.0
+ * (CDDL), a copy of it is provided in the "COPYING.CDDL" file included
+ * in the VirtualBox distribution, in which case the provisions of the
+ * CDDL are applicable instead of those of the GPL.
+ *
+ * You may elect to license modified versions of this file under the
+ * terms and conditions of either the GPL or the CDDL or both.
+ *
+ * SPDX-License-Identifier: GPL-3.0-only OR CDDL-1.0
+ */
+
+#ifndef VBOX_INCLUDED_vmm_dbgfflowtrace_h
+#define VBOX_INCLUDED_vmm_dbgfflowtrace_h
+#ifndef RT_WITHOUT_PRAGMA_ONCE
+# pragma once
+#endif
+
+#include <VBox/types.h>
+#include <VBox/vmm/dbgf.h>
+
+RT_C_DECLS_BEGIN
+/** @defgroup grp_dbgf_flowtrace Guest Execution Flow Tracing
+ * @ingroup grp_dbgf
+ *
+ * @{
+ */
+
+/** A DBGF flow trace module handle. */
+typedef struct DBGFFLOWTRACEMODINT *DBGFFLOWTRACEMOD;
+/** Pointer to a DBGF flow trace module handle. */
+typedef DBGFFLOWTRACEMOD *PDBGFFLOWTRACEMOD;
+/** A DBGF flow trace probe handle. */
+typedef struct DBGFFLOWTRACEPROBEINT *DBGFFLOWTRACEPROBE;
+/** Pointer to a DBGF flow trace state probe handle. */
+typedef DBGFFLOWTRACEPROBE *PDBGFFLOWTRACEPROBE;
+/** A DBGF flow trace report handle. */
+typedef struct DBGFFLOWTRACEREPORTINT *DBGFFLOWTRACEREPORT;
+/** Pointer to a DBGF flow trace report handle. */
+typedef DBGFFLOWTRACEREPORT *PDBGFFLOWTRACEREPORT;
+/** A DBGF flow trace record handle. */
+typedef struct DBGFFLOWTRACERECORDINT *DBGFFLOWTRACERECORD;
+/** Pointer to a DBGF flow trace record handle. */
+typedef DBGFFLOWTRACERECORD *PDBGFFLOWTRACERECORD;
+
+
+/** Pointer to a flow trace probe entry. */
+typedef struct DBGFFLOWTRACEPROBEENTRY *PDBGFFLOWTRACEPROBEENTRY;
+/** Pointer to a const flow trace probe entry. */
+typedef const struct DBGFFLOWTRACEPROBEENTRY *PCDBGFFLOWTRACEPROBEENTRY;
+
+/** @name Flags controlling the type of the addition of a single probe.
+ * @{ */
+/** Default options. */
+#define DBGF_FLOW_TRACE_PROBE_ADD_F_DEFAULT DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC
+/** Collects the data specified by the data probe before the instruction is executed. */
+#define DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC RT_BIT_32(0)
+/** Collects the data specified by the data probe after the instruction was executed. */
+#define DBGF_FLOW_TRACE_PROBE_ADD_F_AFTER_EXEC RT_BIT_32(1)
+/** Mask of all valid flags. */
+#define DBGF_FLOW_TRACE_PROBE_ADD_F_VALID_MASK ( DBGF_FLOW_TRACE_PROBE_ADD_F_BEFORE_EXEC \
+ | DBGF_FLOW_TRACE_PROBE_ADD_F_AFTER_EXEC)
+/** @} */
+
+
+/**
+ * Probe entry type.
+ */
+typedef enum DBGFFLOWTRACEPROBEENTRYTYPE
+{
+ /** Invalid type. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_INVALID = 0,
+ /** Register. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_REG,
+ /** Constant memory buffer pointer. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_CONST_MEM,
+ /** Indirect memory buffer pointer, obtained from the base and index register
+ * and a constant scale. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_INDIRECT_MEM,
+ /** Callback. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_CALLBACK,
+ /** Halt in the debugger when the entry is collected. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_DEBUGGER,
+ /** 32bit hack. */
+ DBGFFLOWTRACEPROBEENTRYTYPE_32BIT_HACK = 0x7fffffff
+} DBGFFLOWTRACEPROBEENTRYTYPE;
+
+
+/**
+ * Register descriptor for a probe entry.
+ */
+typedef struct DBGFFLOWTRACEPROBEENTRYREG
+{
+ /** The register name - see DBGFR3RegNm*. */
+ const char *pszName;
+ /** The size of the value in bytes. */
+ DBGFREGVALTYPE enmType;
+} DBGFFLOWTRACEPROBEENTRYREG;
+/** Pointer to data probe register entry. */
+typedef DBGFFLOWTRACEPROBEENTRYREG *PDBGFFLOWTRACEPROBEENTRYREG;
+/** Pointer to a const probe register entry. */
+typedef const DBGFFLOWTRACEPROBEENTRYREG *PCDBGFFLOWTRACEPROBEENTRYREG;
+
+
+/**
+ * Flow trace probe callback.
+ *
+ * @returns VBox status code, any error aborts continuing fetching the data for the
+ * probe containing this callback.
+ * @param pUVM The usermode VM handle.
+ * @param idCpu The ID of the vCPU the probe as fired.
+ * @param hFlowTraceMod The handle to the flow trace module the probe was fired for.
+ * @param pAddrProbe The guest address the probe was fired at.
+ * @param hFlowTraceProbe The flow trace probe handle.this callback is in.
+ * @param pProbeEntry The probe entry this callback is part of.
+ * @param pvUser The opaque user data for the callback.
+ */
+typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEPROBECALLBACK, (PUVM pUVM, VMCPUID idCpu, DBGFFLOWTRACEMOD hFlowTraceMod,
+ PCDBGFADDRESS pAddrProbe, DBGFFLOWTRACEPROBE hFlowTraceProbe,
+ PCDBGFFLOWTRACEPROBEENTRY pProbeEntry,
+ void *pvUser));
+/** Pointer to a flow trace probe callback. */
+typedef FNDBGFFLOWTRACEPROBECALLBACK *PFNDBGFFLOWTRACEPROBECALLBACK;
+
+
+/**
+ * Trace flow probe entry.
+ */
+typedef struct DBGFFLOWTRACEPROBEENTRY
+{
+ /** Entry type. */
+ DBGFFLOWTRACEPROBEENTRYTYPE enmType;
+ /** Description for this entry, optional. */
+ const char *pszDesc;
+ /** The data based on the entry type. */
+ union
+ {
+ /** Register. */
+ DBGFFLOWTRACEPROBEENTRYREG Reg;
+ /** Constant memory pointer. */
+ struct
+ {
+ /** The address of the memory buffer. */
+ DBGFADDRESS AddrMem;
+ /** Number of bytes to log. */
+ size_t cbMem;
+ } ConstMem;
+ /** Indirect memory */
+ struct
+ {
+ /** The base register. */
+ DBGFFLOWTRACEPROBEENTRYREG RegBase;
+ /** The index register. */
+ DBGFFLOWTRACEPROBEENTRYREG RegIndex;
+ /** The scale to apply to the index. */
+ uint8_t uScale;
+ /** A constant offset which is applied at the end. */
+ RTGCINTPTR iOffset;
+ /** Number of bytes to log. */
+ size_t cbMem;
+ } IndirectMem;
+ /** Callback. */
+ struct
+ {
+ /** The callback to call. */
+ PFNDBGFFLOWTRACEPROBECALLBACK pfnCallback;
+ /** The opaque user data to provide. */
+ void *pvUser;
+ } Callback;
+ } Type;
+} DBGFFLOWTRACEPROBEENTRY;
+
+
+/**
+ * Flow trace probe value.
+ */
+typedef struct DBGFFLOWTRACEPROBEVAL
+{
+ /** Pointer to the flow trace probe entry this value is for. */
+ PCDBGFFLOWTRACEPROBEENTRY pProbeEntry;
+ /** Data based on the type in the entry. */
+ union
+ {
+ /** Register value. */
+ DBGFREGENTRYNM Reg;
+ /** Memory value (constant pointer or indirect). */
+ struct
+ {
+ /** The guest address logged. */
+ DBGFADDRESS Addr;
+ /** Pointer to the data logged. */
+ const void *pvBuf;
+ /** Number of bytes logged. */
+ size_t cbBuf;
+ } Mem;
+ } Type;
+} DBGFFLOWTRACEPROBEVAL;
+/** Pointer to a flow trace probe value. */
+typedef DBGFFLOWTRACEPROBEVAL *PDBGFFLOWTRACEPROBEVAL;
+/** Pointer to a const flow trace probe value. */
+typedef const DBGFFLOWTRACEPROBEVAL *PCDBGFFLOWTRACEPROBEVAL;
+
+/**
+ * Flow trace report filter operation.
+ */
+typedef enum DBGFFLOWTRACEREPORTFILTEROP
+{
+ /** Invalid filter operation. */
+ DBGFFLOWTRACEREPORTFILTEROP_INVALID = 0,
+ /** All filters must match with the record. */
+ DBGFFLOWTRACEREPORTFILTEROP_AND,
+ /** Only one filter must match with the record. */
+ DBGFFLOWTRACEREPORTFILTEROP_OR,
+ /** 32bit hack. */
+ DBGFFLOWTRACEREPORTFILTEROP_32BIT_HACK = 0x7fffffff
+} DBGFFLOWTRACEREPORTFILTEROP;
+
+
+/**
+ * Flow trace report filter type.
+ */
+typedef enum DBGFFLOWTRACEREPORTFILTERTYPE
+{
+ /** Invalid filter type. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_INVALID = 0,
+ /** Filter by sequence number. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_SEQ_NUM,
+ /** Filter by timestamp. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_TIMESTAMP,
+ /** Filter by probe address. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_ADDR,
+ /** Filter by CPU ID. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_VMCPU_ID,
+ /** Filter by specific probe data. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_PROBE_DATA,
+ /** 32bit hack. */
+ DBGFFLOWTRACEREPORTFILTERTYPE_32BIT_HACK = 0x7fffffff
+} DBGFFLOWTRACEREPORTFILTERTYPE;
+
+
+/**
+ * Flow trace report filter.
+ */
+typedef struct DBGFFLOWTRACEREPORTFILTER
+{
+ /** Filter type. */
+ DBGFFLOWTRACEREPORTFILTERTYPE enmType;
+ /** Filter data, type dependent. */
+ struct
+ {
+ /** Sequence number filtering. */
+ struct
+ {
+ /** Sequence number filtering, start value. */
+ uint64_t u64SeqNoFirst;
+ /** Sequence number filtering, last value. */
+ uint64_t u64SeqNoLast;
+ } SeqNo;
+ /** Timestamp filtering. */
+ struct
+ {
+ /** Start value. */
+ uint64_t u64TsFirst;
+ /** Last value. */
+ uint64_t u64TsLast;
+ } Timestamp;
+ /** Probe address filtering. */
+ struct
+ {
+ /** Start address. */
+ DBGFADDRESS AddrStart;
+ /** Last address. */
+ DBGFADDRESS AddrLast;
+ } Addr;
+ /** vCPU id filtering. */
+ struct
+ {
+ /** Start CPU id. */
+ VMCPUID idCpuStart;
+ /** Last CPU id. */
+ VMCPUID idCpuLast;
+ } VCpuId;
+ /** Probe data filtering. */
+ struct
+ {
+ /** Pointer to the probe value array. */
+ PCDBGFFLOWTRACEPROBEVAL paVal;
+ /** Number of entries in the array for filtering. */
+ uint32_t cVals;
+ /** Flag whether to look into the common values or the probe specific ones. */
+ bool fValCmn;
+ } ProbeData;
+ } Type;
+} DBGFFLOWTRACEREPORTFILTER;
+/** Pointer to a flow trace report filter. */
+typedef DBGFFLOWTRACEREPORTFILTER *PDBGFFLOWTRACEREPORTFILTER;
+
+
+/** @name Flags controlling filtering records.
+ * @{ */
+/** Add records which don't match the filter. */
+#define DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE RT_BIT_32(0)
+/** Mask of all valid flags. */
+#define DBGF_FLOW_TRACE_REPORT_FILTER_F_VALID (DBGF_FLOW_TRACE_REPORT_FILTER_F_REVERSE)
+/** @} */
+
+
+/**
+ * Flow trace report enumeration callback.
+ *
+ * @returns VBox status code, any non VINF_SUCCESS code aborts the enumeration and is returned
+ * by DBGFR3FlowTraceReportEnumRecords().
+ * @param hFlowTraceReport The flow trace report handle being enumerated.
+ * @param hFlowTraceRecord The flow trace record handle.
+ * @param pvUser Opaque user data given in DBGFR3FlowTraceReportEnumRecords().
+ */
+typedef DECLCALLBACKTYPE(int, FNDBGFFLOWTRACEREPORTENUMCLBK,(DBGFFLOWTRACEREPORT hFlowTraceReport,
+ DBGFFLOWTRACERECORD hFlowTraceRecord,
+ void *pvUser));
+/** Pointer to a record enumeration callback. */
+typedef FNDBGFFLOWTRACEREPORTENUMCLBK *PFNDBGFFLOWTRACEREPORTENUMCLBK;
+
+
+VMMR3DECL(int) DBGFR3FlowTraceModCreate(PUVM pUVM, VMCPUID idCpu,
+ DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
+ PDBGFFLOWTRACEMOD phFlowTraceMod);
+VMMR3DECL(int) DBGFR3FlowTraceModCreateFromFlowGraph(PUVM pUVM, VMCPUID idCpu, DBGFFLOW hFlow,
+ DBGFFLOWTRACEPROBE hFlowTraceProbeCommon,
+ DBGFFLOWTRACEPROBE hFlowTraceProbeEntry,
+ DBGFFLOWTRACEPROBE hFlowTraceProbeRegular,
+ DBGFFLOWTRACEPROBE hFlowTraceProbeExit,
+ PDBGFFLOWTRACEMOD phFlowTraceMod);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceModRetain(DBGFFLOWTRACEMOD hFlowTraceMod);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceModRelease(DBGFFLOWTRACEMOD hFlowTraceMod);
+VMMR3DECL(int) DBGFR3FlowTraceModEnable(DBGFFLOWTRACEMOD hFlowTraceMod, uint32_t cHits, uint32_t cRecordsMax);
+VMMR3DECL(int) DBGFR3FlowTraceModDisable(DBGFFLOWTRACEMOD hFlowTraceMod);
+VMMR3DECL(int) DBGFR3FlowTraceModQueryReport(DBGFFLOWTRACEMOD hFlowTraceMod,
+ PDBGFFLOWTRACEREPORT phFlowTraceReport);
+VMMR3DECL(int) DBGFR3FlowTraceModClear(DBGFFLOWTRACEMOD hFlowTraceMod);
+VMMR3DECL(int) DBGFR3FlowTraceModAddProbe(DBGFFLOWTRACEMOD hFlowTraceMod, PCDBGFADDRESS pAddrProbe,
+ DBGFFLOWTRACEPROBE hFlowTraceProbe, uint32_t fFlags);
+
+VMMR3DECL(int) DBGFR3FlowTraceProbeCreate(PUVM pUVM, const char *pszDescr, PDBGFFLOWTRACEPROBE phFlowTraceProbe);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRetain(DBGFFLOWTRACEPROBE hFlowTraceProbe);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceProbeRelease(DBGFFLOWTRACEPROBE hFlowTraceProbe);
+VMMR3DECL(int) DBGFR3FlowTraceProbeEntriesAdd(DBGFFLOWTRACEPROBE hFlowTraceProbe,
+ PCDBGFFLOWTRACEPROBEENTRY paEntries, uint32_t cEntries);
+
+VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRetain(DBGFFLOWTRACEREPORT hFlowTraceReport);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceReportRelease(DBGFFLOWTRACEREPORT hFlowTraceReport);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceReportGetRecordCount(DBGFFLOWTRACEREPORT hFlowTraceReport);
+VMMR3DECL(int) DBGFR3FlowTraceReportQueryRecord(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t idxRec, PDBGFFLOWTRACERECORD phFlowTraceRec);
+VMMR3DECL(int) DBGFR3FlowTraceReportQueryFiltered(DBGFFLOWTRACEREPORT hFlowTraceReport, uint32_t fFlags,
+ PDBGFFLOWTRACEREPORTFILTER paFilters, uint32_t cFilters,
+ DBGFFLOWTRACEREPORTFILTEROP enmOp,
+ PDBGFFLOWTRACEREPORT phFlowTraceReportFiltered);
+VMMR3DECL(int) DBGFR3FlowTraceReportEnumRecords(DBGFFLOWTRACEREPORT hFlowTraceReport,
+ PFNDBGFFLOWTRACEREPORTENUMCLBK pfnEnum,
+ void *pvUser);
+
+VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRetain(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordRelease(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetSeqNo(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(uint64_t) DBGFR3FlowTraceRecordGetTimestamp(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(PDBGFADDRESS) DBGFR3FlowTraceRecordGetAddr(DBGFFLOWTRACERECORD hFlowTraceRecord, PDBGFADDRESS pAddr);
+VMMR3DECL(DBGFFLOWTRACEPROBE) DBGFR3FlowTraceRecordGetProbe(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(uint32_t) DBGFR3FlowTraceRecordGetValCommonCount(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetVals(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(PCDBGFFLOWTRACEPROBEVAL) DBGFR3FlowTraceRecordGetValsCommon(DBGFFLOWTRACERECORD hFlowTraceRecord);
+VMMR3DECL(VMCPUID) DBGFR3FlowTraceRecordGetCpuId(DBGFFLOWTRACERECORD hFlowTraceRecord);
+
+/** @} */
+RT_C_DECLS_END
+
+#endif /* !VBOX_INCLUDED_vmm_dbgfflowtrace_h */
+